<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta name="language" content="en">
<meta name="date" content="2017-04-17T13:28:24">
<meta name="generator" content="deplate.rb 0.8.5">
<title>User&rsquo;s Guide for VirtualGL 2.5.3</title>
<link rel="start" href="index.html" title="Frontpage">
<link rel="chapter" href="index.html#hd001" title="1 Legal Information">
<link rel="chapter" href="index.html#hd002" title="2 Conventions Used in This Document">
<link rel="chapter" href="index.html#hd003" title="3 Overview">
<link rel="chapter" href="index.html#hd004" title="4 System Requirements">
<link rel="chapter" href="index.html#hd005" title="5 Obtaining and Installing VirtualGL">
<link rel="chapter" href="index.html#hd006" title="6 Configuring a Linux or Unix Machine as a VirtualGL Server">
<link rel="chapter" href="index.html#hd007" title="7 Configuring a Windows Machine as a VGL Transport Client">
<link rel="chapter" href="index.html#hd008" title="8 Using VirtualGL with the VGL Transport">
<link rel="chapter" href="index.html#hd009" title="9 Using VirtualGL with X Proxies Such as VNC">
<link rel="chapter" href="index.html#hd0010" title="10 Support for the X Video Extension">
<link rel="chapter" href="index.html#hd0011" title="11 Transport Plugins">
<link rel="chapter" href="index.html#hd0012" title="12 Using VirtualGL with setuid/setgid Executables">
<link rel="chapter" href="index.html#hd0013" title="13 Using VirtualGL with VirtualBox">
<link rel="chapter" href="index.html#hd0014" title="14 Using VirtualGL with VMWare Workstation">
<link rel="chapter" href="index.html#hd0015" title="15 Other Application Recipes">
<link rel="chapter" href="index.html#hd0016" title="16 Advanced OpenGL Features">
<link rel="chapter" href="index.html#hd0017" title="17 Performance Measurement">
<link rel="chapter" href="index.html#hd0018" title="18 The VirtualGL Configuration Dialog">
<link rel="chapter" href="index.html#hd0019" title="19 Advanced Configuration">
<link rel="stylesheet" type="text/css" href="virtualgl.css" title="virtualgl">
</head>
<body >
<a name="#pagetop"></a>
<div class="title">
<p class="title">User&rsquo;s Guide for VirtualGL 2.5.3</p>
</div>
<a name="file000"></a>
<p><em>Intended audience:</em> System Administrators, Graphics Programmers, 
Researchers, and others with knowledge of Linux or Unix operating 
systems, OpenGL and GLX, and X windows.</p>

<div id="hd">
<div id="hdBlock" class="hd">
<ul class="hd">
    <li class="Itemize-1 hd">
        <a href="#hd001" class="hd">1 Legal Information</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd002" class="hd">2 Conventions Used in This Document</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd003" class="hd">3 Overview</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd004" class="hd">4 System Requirements</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd004001" class="hd">4.1 Linux/x86 and Other x86 Un*x 
                Operating Systems</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd004002" class="hd">4.2 Mac/x86</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd004003" class="hd">4.3 Windows</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd004004" class="hd">4.4 Additional Requirements for 
                Stereographic Rendering</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd004005" class="hd">4.5 Additional Requirements for 
                Transparent Overlays</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd005" class="hd">5 Obtaining and Installing VirtualGL</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd005001" class="hd">5.1 Installing VirtualGL on Linux</a>
                <ul class="hd">
                    <li class="Itemize-5 hd">
                        <a href="#hd005001001" class="hd">5.1.1 Installing a 32-bit VirtualGL 
                        Package on x86-64 Linux Distributions</a>
                    </li>
                </ul>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd005002" class="hd">5.2 Installing the VirtualGL Client on OS 
                X</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd005003" class="hd">5.3 Installing the VirtualGL Client on 
                Windows (Cygwin)</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd005004" class="hd">5.4 Installing VirtualGL from Source</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd005005" class="hd">5.5 Uninstalling VirtualGL</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd006" class="hd">6 Configuring a Linux or Unix Machine as a 
        VirtualGL Server</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd006001" class="hd">6.1 Initial System Configuration</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd006002" class="hd">6.2 Granting Access to the 3D X Server</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd006003" class="hd">6.3 Using VirtualGL with Multiple GPUs</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd006004" class="hd">6.4 SSH Server Configuration</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd006005" class="hd">6.5 Un-Configuring the Server</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd007" class="hd">7 Configuring a Windows Machine as a VGL 
        Transport Client</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd008" class="hd">8 Using VirtualGL with the VGL Transport</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd008001" class="hd">8.1 VGL Transport with X11 Forwarding</a>
                <ul class="hd">
                    <li class="Itemize-5 hd">
                        <a href="#hd008001001" class="hd">8.1.1 Procedure</a>
                    </li>
                </ul>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008002" class="hd">8.2 VGL Transport with a Direct X11 
                Connection</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008003" class="hd">8.3 VGL Transport with X11 Forwarding and 
                SSH Tunneling</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008004" class="hd">8.4 VGL Transport over Gigabit 
                Networks</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008005" class="hd">8.5 VGL Transport with XDMCP</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008006" class="hd">8.6 The VirtualGL Client Application: 
                Nuts and Bolts</a>
                <ul class="hd">
                    <li class="Itemize-5 hd">
                        <a href="#hd008006001" class="hd">8.6.1 The VirtualGL Client and 
                        Firewalls</a>
                    </li>
                </ul>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd009" class="hd">9 Using VirtualGL with X Proxies Such as 
        VNC</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd009001" class="hd">9.1 Using VirtualGL with an X Proxy on 
                the Same Server</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd009002" class="hd">9.2 Using VirtualGL with an X Proxy on a 
                Different Machine</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0010" class="hd">10 Support for the X Video Extension</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd0010001" class="hd">10.1 The VGL Transport with YUV 
                Encoding</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0010002" class="hd">10.2 The XV Transport</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0011" class="hd">11 Transport Plugins</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0012" class="hd">12 Using VirtualGL with setuid/setgid 
        Executables</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0013" class="hd">13 Using VirtualGL with VirtualBox</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0014" class="hd">14 Using VirtualGL with VMWare 
        Workstation</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0015" class="hd">15 Other Application Recipes</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0016" class="hd">16 Advanced OpenGL Features</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd0016001" class="hd">16.1 Stereographic Rendering</a>
                <ul class="hd">
                    <li class="Itemize-5 hd">
                        <a href="#hd0016001001" class="hd">16.1.1 Quad-Buffered Stereo</a>
                    </li>
                    <li class="Itemize-5 hd">
                        <a href="#hd0016001002" class="hd">16.1.2 Anaglyphic Stereo</a>
                    </li>
                    <li class="Itemize-5 hd">
                        <a href="#hd0016001003" class="hd">16.1.3 Passive Stereo</a>
                    </li>
                    <li class="Itemize-5 hd">
                        <a href="#hd0016001004" class="hd">16.1.4 Selecting a Stereo Mode</a>
                    </li>
                </ul>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0016002" class="hd">16.2 Transparent Overlays</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0016003" class="hd">16.3 Troubleshooting</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0017" class="hd">17 Performance Measurement</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd0017001" class="hd">17.1 VirtualGL&rsquo;s Built-In 
                Profiling System</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0017002" class="hd">17.2 Frame Spoiling</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0017003" class="hd">17.3 VirtualGL Diagnostic Tools</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0018" class="hd">18 The VirtualGL Configuration Dialog</a>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd0019" class="hd">19 Advanced Configuration</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd0019001" class="hd">19.1 Server Settings</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd0019002" class="hd">19.2 Client Settings</a>
            </li>
        </ul>
    </li>
</ul>
</div></div>
<p><br /></p>

<hr class="break" />


<h1 id="hd001"><a name="file001"></a>1&nbsp;Legal Information</h1>

<p><img src="somerights20.png" alt="somerights20" class="inline" id="imgid_0" name="imgid_0"/></p>

<p>This document and all associated illustrations are licensed under the 
<span class="remote"><a href="http://creativecommons.org/licenses/by/2.5/" class="remote">Creative 
Commons Attribution 2.5 License</a></span><a name="idx001"></a>.  Any 
works that contain material derived from this document must cite The 
VirtualGL Project as the source of the material and list the current URL 
for the VirtualGL web site.</p>

<p>The official VirtualGL binaries contain libjpeg-turbo, which is based in 
part on the work of the Independent JPEG Group.</p>

<p>The VirtualGL server components include software developed by the 
<span class="remote"><a href="http://www.fltk.org/" class="remote">FLTK 
Project</a></span><a name="idx002"></a> and distributed under the terms 
of the <a href="LICENSE-FLTK.txt">FLTK License</a><a name="idx003"></a>.</p>

<p>VirtualGL is licensed under the <a href="LICENSE.txt">wxWindows Library 
License, v3.1</a><a name="idx004"></a>, a derivative of the 
<a href="LGPL.txt">GNU Lesser General Public License (LGPL), 
v2.1</a><a name="idx005"></a>.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd002"><a name="file002"></a>2&nbsp;Conventions Used in This Document</h1>

<p>This document assumes that VirtualGL will be installed in the default 
directory (<code>/opt/VirtualGL</code>).  If your installation of 
VirtualGL resides in a different directory, then adjust the instructions 
accordingly.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd003"><a name="file003"></a>3&nbsp;Overview</h1>

<p><a name="Overview"></a></p>

<p>VirtualGL is an open source toolkit that gives any Unix or Linux remote 
display software the ability to run OpenGL applications with full 3D 
hardware acceleration.  Some remote display solutions cannot be used 
with OpenGL applications at all.  Others force OpenGL applications to 
use a slow, software-only renderer, to the detriment of performance as 
well as compatibility.  The traditional method of displaying OpenGL 
applications to a remote X server (indirect rendering) supports 3D 
hardware acceleration, but this approach causes all of the OpenGL 
commands and 3D data to be sent over the network to be rendered on the 
client machine.  This is not a tenable proposition unless the data is 
relatively small and static, unless the network is very fast, and unless 
the OpenGL application is specifically tuned for a remote X-Windows 
environment.</p>

<p>With VirtualGL, the OpenGL commands and 3D data are instead redirected 
to a 3D graphics accelerator (AKA &ldquo;graphics processing unit&rdquo; 
or &ldquo;GPU&rdquo;) in the application server, and only the rendered 
3D images are sent to the client machine.  VirtualGL thus 
&ldquo;virtualizes&rdquo; 3D graphics hardware, allowing it to be 
co-located in the &ldquo;cold room&rdquo; with compute and storage 
resources.  VirtualGL also allows GPUs to be shared among multiple 
users, and it provides &ldquo;workstation-like&rdquo; levels of 
performance on even the most modest of networks. This makes it possible 
for large, noisy, hot 3D workstations to be replaced with laptops or 
even thinner clients.  More importantly, however, VirtualGL eliminates 
the workstation and the network as barriers to data size.  Users can now 
visualize huge amounts of data in real time without needing to copy any 
of the data over the network or sit in front of the machine that is 
rendering the data.</p>

<p>Normally, a Unix OpenGL application would send all of its drawing 
commands and data, both 2D and 3D, to an X-Windows server, which may be 
located across the network from the application server.  VirtualGL, 
however, employs a technique called &ldquo;split rendering&rdquo; to 
force the 3D commands and data from the application to go to a GPU in 
the application server.  VGL accomplishes this by pre-loading a dynamic 
shared object (DSO) into the OpenGL application at run time.  This DSO 
intercepts a handful of GLX, OpenGL, and X11 commands necessary to 
perform split rendering.  When the application attempts to use an X 
window for OpenGL rendering, VirtualGL intercepts the request, creates a 
corresponding 3D pixel buffer (&ldquo;Pbuffer&rdquo;) in video memory on 
the application server, and uses the Pbuffer for OpenGL rendering 
instead.  When the application swaps the OpenGL drawing buffers or 
flushes the OpenGL command buffer to indicate that it has finished 
rendering a frame, VirtualGL reads back the pixels from the Pbuffer and 
sends them to the client.</p>

<p>The beauty of this approach is its non-intrusiveness.  VirtualGL 
monitors a few X11 commands and events to determine when windows have 
been resized, etc., but it does not interfere in any way with the 
delivery of 2D X11 commands to the X server.  For the most part, VGL 
does not interfere with the delivery of OpenGL commands to the GPU, 
either.  VGL merely forces the OpenGL commands to be delivered to a GPU 
that is attached to a different X server (the &ldquo;3D X server&rdquo;) 
than the X server to which the 2D drawing commands are delivered (the 
&ldquo;2D X server.&rdquo;)  Once the OpenGL rendering has been 
redirected to a Pbuffer, everything (including esoteric OpenGL 
extensions, fragment/vertex programs, etc.) should &ldquo;just 
work.&rdquo;  If an application runs locally on a 3D server/workstation, 
then that same application should run remotely from that same machine 
using VirtualGL.</p>

<p>VirtualGL has two built-in &ldquo;image transports&rdquo; that can be 
used to send rendered 3D images to the client machine:</p>

<p><a name="VGL_Transport"></a></p>

<dl class="Description">
    <dt class="Description-1 Description">1. VGL Transport</dt>
    <dd class="Description-1 Description">
        The VGL Transport is most often used whenever the 2D X server (the X 
        server used to draw the application&rsquo;s GUI and transmit keyboard 
        and mouse events back to the application server) is located across the 
        network from the application server, for instance if the 2D X server is 
        running on the user&rsquo;s desktop machine.  VirtualGL uses its own 
        protocol on a dedicated TCP socket to send the rendered 3D images to the 
        client machine, and the VirtualGL Client application decodes the images 
        and composites them into the appropriate X window.  The VGL Transport 
        can either deliver uncompressed images (RGB-encoded), or it can compress 
        images in real time using a high-speed JPEG codec.  It also supports the 
        delivery of stereo image pairs, which can be reconstructed into a stereo 
        image by the VirtualGL Client.
    </dd>
</dl>

<a name="fig003001"></a>
<div class="figure">
<p class="caption">Figure 3.1: The VGL Transport with a Remote 2D X Server</p>
<img src="vgltransport.png" alt="vgltransport" class="figure" id="imgid_5" name="imgid_5"/>
</div>

<p><a name="X11_Transport"></a></p>

<dl class="Description">
    <dt class="Description-1 Description">2. X11 Transport</dt>
    <dd class="Description-1 Description">
        The X11 Transport simply draws the rendered 3D images into the 
        appropriate X window using <code>XPutImage()</code> and similar 
        X-Windows commands.  This is most useful in conjunction with an &ldquo;X 
        proxy&rdquo;, which can be one of any number of Unix remote display 
        applications, such as VNC.  These X proxies are essentially 
        &ldquo;virtual&rdquo; X servers.  They appear to the application as a 
        normal X server, but they perform X11 rendering to a virtual framebuffer 
        in main memory rather than to a real framebuffer (video memory.)  This 
        allows the X proxy to send only images to the client machine rather than 
        fine-grained X-Windows rendering commands.  When using the X11 
        Transport, VirtualGL does not perform any image compression or encoding 
        itself.  It instead relies upon an X proxy to encode and deliver the 
        images to the client(s).  Since the use of an X proxy eliminates the 
        need to send X-Windows commands over the network, this is the best means 
        of using VirtualGL over high-latency or low-bandwidth networks.
    </dd>
</dl>

<a name="fig003002"></a>
<div class="figure">
<p class="caption">Figure 3.2: The X11 Transport with an X Proxy</p>
<img src="x11transport.png" alt="x11transport" class="figure" id="imgid_6" name="imgid_6"/>
</div>

<p>VirtualGL also provides an API that can be used to develop custom image 
transport plugins.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd004"><a name="file004"></a>4&nbsp;System Requirements</h1>


<h2 id="hd004001">4.1&nbsp;Linux/x86 and Other x86 Un*x Operating Systems</h2>

<p><a name="Linux_Requirements"></a></p>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard"></th>
    <th class="head standard">Server (x86)</th>
    <th class="head standard">Server (x86-64)</th>
    <th class="head standard">Client</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="high standard">Recommended CPU</td>
    <td class="standard"><ul class="Itemize"><li class="Itemize-0">
    For optimal performance, the CPU should support SSE2 extensions.
</li>
<li class="Itemize-0">
    Dual processors or dual cores recommended
</li></ul></td>
    <td class="standard">Dual processors or dual cores recommended</td>
    <td class="standard">For optimal performance, the CPU should support SSE2 extensions.</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Graphics</td>
    <td class="standard" colspan="2">AMD or nVidia GPU <ul class="Itemize"><li class="Itemize-0">
    For optimal performance, particularly with multiple simultaneous users, 
    a professional-grade GPU such as the AMD FirePro or nVidia Quadro is 
    recommended.
</li>
<li class="Itemize-0">
    Install the AMD or nVidia proprietary drivers.  Open source drivers for 
    these GPUs do not generally provide full 3D acceleration, and some of 
    those drivers do not provide Pbuffer support.
</li></ul></td>
    <td class="standard">Any graphics adapter with decent 2D performance <ul class="Itemize"><li class="Itemize-0">
    If using a 3D graphics adapter, install the vendor drivers for that 3D 
    graphics adapter.
</li></ul></td>
  </tr>
  <tr class="standard">
    <td class="high standard">O/S</td>
    <td class="standard" colspan="3">VirtualGL should work with a variety of Linux distributions, <span class="remote"><a href="http://www.freebsd.org" class="remote">FreeBSD</a></span><a name="idx006"></a>, and <span class="remote"><a href="http://www.oracle.com/us/products/servers-storage/solaris" class="remote">Solaris</a></span><a name="idx007"></a>, but currently-supported versions of <span class="remote"><a href="http://www.redhat.com/products/enterprise-linux/" class="remote">Red Hat Enterprise Linux</a></span><a name="idx008"></a> (and its work-alikes, including <span class="remote"><a href="http://www.centos.org" class="remote">CentOS</a></span><a name="idx009"></a>, <span class="remote"><a href="http://www.oracle.com/us/technologies/linux" class="remote">Oracle Linux</a></span><a name="idx0010"></a>, and <span class="remote"><a href="https://www.scientificlinux.org" class="remote">Scientific Linux</a></span><a name="idx0011"></a>), <span class="remote"><a href="http://www.ubuntu.com" class="remote">Ubuntu</a></span><a name="idx0012"></a> LTS, and <span class="remote"><a href="http://www.suse.com" class="remote">SuSE</a></span><a name="idx0013"></a> Linux Enterprise tend to receive the most attention from the VirtualGL community.</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Other Software</td>
    <td class="standard" colspan="3">X server configured to export True Color (24-bit or 32-bit) visuals</td>
  </tr>
</table>
</div>




<h2 id="hd004002">4.2&nbsp;Mac/x86</h2>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard"></th>
    <th class="head standard">Client</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="high standard">Recommended CPU</td>
    <td class="standard">Any Intel-based Mac</td>
  </tr>
  <tr class="standard">
    <td class="high standard">O/S</td>
    <td class="standard">OS X 10.5 (&ldquo;Leopard&rdquo;) or later</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Other Software</td>
    <td class="standard"><ul class="Itemize"><li class="Itemize-0">
    <em>VGL Transport Only</em>: Mac X11 application (in the &ldquo;Optional 
    Installs&rdquo; package on the OS X 10.7 and earlier install discs) or 
    <span class="remote"><a href="http://xquartz.macosforge.org" class="remote">XQuartz</a></span><a name="idx0014"></a>
</li></ul></td>
  </tr>
</table>
</div>




<h2 id="hd004003">4.3&nbsp;Windows</h2>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard"></th>
    <th class="head standard">Client</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="high standard">Recommended CPU</td>
    <td class="standard">For optimal performance, the CPU should support SSE2 extensions.</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Graphics</td>
    <td class="standard">Any graphics adapter with decent 2D performance</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Other Software</td>
    <td class="standard"><ul class="Itemize"><li class="Itemize-0">
    <em>VGL Transport Only</em>: 
    <span class="remote"><a href="http://x.cygwin.com" class="remote">Cygwin/X</a></span><a name="idx0015"></a>
</li>
<li class="Itemize-0">
    Client display must have a 24-bit or 32-bit color depth (True Color.)
</li></ul></td>
  </tr>
</table>
</div>




<h2 id="hd004004">4.4&nbsp;Additional Requirements for Stereographic Rendering</h2>

<p><a name="Stereo_Requirements"></a></p>

<div class="important"><p class="important">
The client requirements do not apply to anaglyphic stereo.  See Chapter <a href="#Advanced_OpenGL" class="ref">16</a> for more details.
</p></div>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard"></th>
    <th class="head standard">Server</th>
    <th class="head standard">Client</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="high standard">Linux/Unix</td>
    <td class="standard"><ul class="Itemize"><li class="Itemize-0">
    AMD or nVidia GPU that supports stereo (examples: AMD FirePro W Series, 
    nVidia Quadro)
</li>
<li class="Itemize-0">
    The 3D X server should be configured to export stereo visuals.
</li></ul></td>
    <td class="standard"><ul class="Itemize"><li class="Itemize-0">
    GPU that supports stereo
</li>
<li class="Itemize-0">
    The 2D X server should be configured to export stereo visuals.
</li></ul></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Mac/x86</td>
    <td class="standard">N/A</td>
    <td class="standard">GPU that supports stereo (example: nVidia Quadro)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Windows</td>
    <td class="standard">N/A</td>
    <td class="standard">This version of VirtualGL does not support remote quad-buffered stereo with Windows clients.</td>
  </tr>
</table>
</div>




<h2 id="hd004005">4.5&nbsp;Additional Requirements for Transparent Overlays</h2>

<p><a name="Overlay_Requirements"></a></p>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard"></th>
    <th class="head standard">Client</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="high standard">Linux/Unix</td>
    <td class="standard" rowspan="2">GPU that supports transparent overlays.  The 2D X server should be configured to export overlay visuals.</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Mac/x86</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Windows</td>
    <td class="standard">This version of VirtualGL does not support transparent overlays with Windows clients.</td>
  </tr>
</table>
</div>


<p><br /></p>

<hr class="break" />



<h1 id="hd005"><a name="file005"></a>5&nbsp;Obtaining and Installing VirtualGL</h1>

<div class="important"><p class="important">
VirtualGL must be installed on any machine that will act as a VirtualGL server or as a client for the <a href="#VGL_Transport">VGL Transport</a><a name="idx0016"></a>. It is not necessary to install VirtualGL on the client machine if using VNC or another type of X proxy.
</p></div>


<h2 id="hd005001">5.1&nbsp;Installing VirtualGL on Linux</h2>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered" value="1">
        Download the appropriate VirtualGL binary package(s) for your system 
        from the 
        <span class="remote"><a href="http://sourceforge.net/projects/virtualgl/files" class="remote">Files 
        area</a></span><a name="idx0017"></a> of the 
        <span class="remote"><a href="http://sourceforge.net/projects/virtualgl" class="remote">VirtualGL 
        SourceForge project page</a></span><a name="idx0018"></a>. Packages are 
        provided for RPM-based and Debian-based Linux distributions that contain 
        GLIBC 2.5 or later (including 
        <span class="remote"><a href="http://fedoraproject.org" class="remote">Fedora</a></span><a name="idx0019"></a> 
        6 or later, 
        <span class="remote"><a href="http://www.redhat.com/products/enterprise-linux" class="remote">Red 
        Hat Enterprise 
        Linux</a></span><a name="idx0020"></a>/<span class="remote"><a href="http://www.centos.org/" class="remote">CentOS</a></span><a name="idx0021"></a> 
        5 or later, 
        <span class="remote"><a href="http://www.suse.com" class="remote">SuSE</a></span><a name="idx0022"></a> 
        Linux 
        Enterprise/<span class="remote"><a href="http://www.opensuse.org" class="remote">openSUSE</a></span><a name="idx0023"></a> 
        11 or later, and 
        <span class="remote"><a href="http://www.ubuntu.com" class="remote">Ubuntu</a></span><a name="idx0024"></a> 
        8.04 or later.) <br />
        <div class="important"><p class="important">
        If you want to run both 32-bit and 64-bit OpenGL applications using VirtualGL on 64-bit Linux systems, then you will need to install both the i386 and x86_64 VirtualGL RPMs or both the &ldquo;virtualgl&rdquo; and &ldquo;virtualgl32&rdquo; amd64 DEBs.  (The virtualgl32 DEB is a supplementary package that contains only the 32-bit server components.)
        </p></div>
    </li>
    <li class="Ordered-1 Ordered" value="2">
        cd to the directory where you downloaded the binary package(s), and 
        issue the following commands as root:
        <dl class="Description">
            <dt class="Description-3 Description">RPM-based systems using YUM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
rpm&nbsp;-e&nbsp;VirtualGL&nbsp;--allmatches
yum&nbsp;install&nbsp;VirtualGL*.rpm
</pre>

            </dd>
            <dt class="Description-3 Description">RPM-based systems using DNF</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
rpm&nbsp;-e&nbsp;VirtualGL&nbsp;--allmatches
dnf&nbsp;install&nbsp;VirtualGL*.rpm
</pre>

            </dd>
            <dt class="Description-3 Description">RPM-based systems using YaST2</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
rpm&nbsp;-e&nbsp;VirtualGL&nbsp;--allmatches
yast2&nbsp;--install&nbsp;VirtualGL*.rpm
</pre>

            </dd>
            <dt class="Description-3 Description">Other RPM-based systems (dependencies will not be installed automatically)</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
rpm&nbsp;-e&nbsp;VirtualGL&nbsp;--allmatches
rpm&nbsp;-i&nbsp;VirtualGL*.rpm
</pre>

            </dd>
            <dt class="Description-3 Description">Debian-based systems (dependencies will not be installed automatically)</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
dpkg&nbsp;-i&nbsp;virtualgl*.deb
</pre>

            </dd>
        </dl>
    </li>
</ol>


<h3 id="hd005001001">5.1.1&nbsp;Installing a 32-bit VirtualGL Package on x86-64 Linux Distributions</h3>

<p>In order to run 32-bit OpenGL applications in VirtualGL, it is necessary 
to install the 32-bit VirtualGL server components, which depend on a few 
32-bit system libraries.  Recent x86-64 Linux distributions do not 
include 32-bit libraries by default, so it will be necessary to perform 
a few additional steps prior to installing a 32-bit VirtualGL package on 
some of those distributions.</p>

<dl class="Description">
    <dt class="Description-1 Description">Red Hat Enterprise Linux 6+ (and work-alikes), Recent Fedora Releases, SuSE/openSUSE</dt>
    <dd class="Description-1 Description">
        <br class="itempara" />No additional steps are necessary. <code>yum&nbsp;install</code> / 
        <code>dnf&nbsp;install</code> / <code>yast2&nbsp;--install</code> takes 
        care of all of the dependencies for both the 64-bit and 32-bit RPMs.
    </dd>
    <dt class="Description-1 Description">Ubuntu 12 and later</dt>
    <dd class="Description-1 Description">
        <br class="itempara" />Run the following command as root prior to installing the virtualgl32 
        package:
<pre class="verbatim">
apt-get&nbsp;install&nbsp;libxv1:i386&nbsp;libglu1-mesa:i386
</pre>

    </dd>
</dl>



<h2 id="hd005002">5.2&nbsp;Installing the VirtualGL Client on OS X</h2>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Download the VirtualGL Mac disk image 
        (<code>VirtualGL-</code><em><code>{version}</code></em><code>.dmg</code>) 
        from the 
        <span class="remote"><a href="http://sourceforge.net/projects/virtualgl/files" class="remote">Files 
        area</a></span><a name="idx0025"></a> of the 
        <span class="remote"><a href="http://sourceforge.net/projects/virtualgl" class="remote">VirtualGL 
        SourceForge project page</a></span><a name="idx0026"></a>.
    </li>
    <li class="Ordered-1 Ordered">
        Open the disk image, then open 
        <code>VirtualGL-</code><em><code>{version}</code></em><code>.pkg</code> 
        inside the disk image.  Follow the instructions to install the Mac 
        client.
    </li>
</ol>



<h2 id="hd005003">5.3&nbsp;Installing the VirtualGL Client on Windows (Cygwin)</h2>

<p>Refer to 
<span class="remote"><a href="http://www.virtualgl.org/Documentation/Cygwin" class="remote">http://www.virtualgl.org/Documentation/Cygwin</a></span><a name="idx0027"></a>.</p>



<h2 id="hd005004">5.4&nbsp;Installing VirtualGL from Source</h2>

<p>If you are using a platform for which there is not a pre-built VirtualGL 
binary package available, then download the VirtualGL source tarball 
(<code>VirtualGL-</code><em><code>{version}</code></em><code>.tar.gz</code>) 
from the 
<span class="remote"><a href="http://sourceforge.net/projects/virtualgl/files" class="remote">Files 
area</a></span><a name="idx0028"></a> of the 
<span class="remote"><a href="http://sourceforge.net/projects/virtualgl" class="remote">VirtualGL 
SourceForge project page</a></span><a name="idx0029"></a>, uncompress 
it, <code>cd&nbsp;VirtualGL-</code><em><code>{version}</code></em>, and 
read the contents of <code>BUILDING.txt</code> for further instructions 
on how to build and install VirtualGL from source.</p>



<h2 id="hd005005">5.5&nbsp;Uninstalling VirtualGL</h2>


<h3 id="hd005005001">Linux</h3>

<p>As root, issue one of the following commands:</p>

<dl class="Description">
    <dt class="Description-1 Description">RPM-based systems</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
rpm&nbsp;-e&nbsp;VirtualGL
</pre>

        <div class="important"><p class="important">
        You may need to add <code>--all-matches</code> to the RPM command line if you have installed both the 32-bit and 64-bit VirtualGL RPMs.
        </p></div>
    </dd>
    <dt class="Description-1 Description">Debian-based systems</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
dpkg&nbsp;-r&nbsp;virtualgl
</pre>

        If you have also installed the 32-bit supplementary package:
<pre class="verbatim">
dpkg&nbsp;-r&nbsp;virtualgl32
</pre>

    </dd>
</dl>



<h3 id="hd005005002">OS X</h3>

<p>Use the &ldquo;Uninstall VirtualGL&rdquo; application provided in the 
VirtualGL disk image, or issue the following command from the Terminal:</p>

<pre class="verbatim">
sudo&nbsp;/opt/VirtualGL/bin/uninstall
</pre>



<h3 id="hd005005003">Windows (Cygwin)</h3>

<p>Refer to 
<span class="remote"><a href="http://www.virtualgl.org/Documentation/Cygwin" class="remote">http://www.virtualgl.org/Documentation/Cygwin</a></span><a name="idx0030"></a>.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd006"><a name="file006"></a>6&nbsp;Configuring a Linux or Unix Machine as a VirtualGL Server</h1>

<p><a name="Unix_Config"></a></p>


<h2 id="hd006001">6.1&nbsp;Initial System Configuration</h2>

<p>Before configuring VirtualGL, you should first ensure that:</p>

<p>1. The appropriate GPU drivers have been installed on the machine.  With 
few exceptions, you should install the drivers supplied by your GPU 
vendor rather than the drivers supplied by your O/S distribution.  See 
Section <a href="#Linux_Requirements" class="ref">4.1</a>.</p>

<p>2. The 3D X server (that is, the &ldquo;local&rdquo; X server on the 
VirtualGL server machine) has been configured to use the GPU drivers you 
installed above.</p>

<p>3. The machine has an appropriate display manager (such as GDM, KDM, or 
LightDM) installed and has been configured to start the display manager 
and 3D X server at boot time.  This is the default with most modern 
Linux and Unix distributions.</p>

<p>4. Accelerated OpenGL is working properly in the 3D X server.</p>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        If the 3D X server is not headless, then this can be verified by logging 
        into the X server locally and running <code>glxinfo</code>.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        If the 3D X server is headless, then proceed with the	instructions 
        below, and the &ldquo;Sanity Check&rdquo; section will provide you with 
        an opportunity to verify that the 3D X server is using accelerated 
        OpenGL.
    </li>
</ul>

<p>More specific instructions are unfortunately outside of the scope of 
this guide, since they will vary from system to system.</p>



<h2 id="hd006002">6.2&nbsp;Granting Access to the 3D X Server</h2>

<p>VirtualGL requires access to a GPU in the application server so that it 
can create off-screen pixel buffers (Pbuffers) and redirect the 3D 
rendering from X windows into these Pbuffers.  Unfortunately, accessing 
a GPU on Linux and Unix systems requires going through an X server.  On 
such systems, the only way to share the application server&rsquo;s 
GPU(s) among multiple users is to grant those users access to the 3D X 
server (the X server attached to the GPU(s).  Refer to the figures in 
Chapter <a href="#Overview" class="ref">3</a>.)</p>

<p>It is important to understand the security risks associated with this.  
Once a user has access to the 3D X server, there is nothing that would 
prevent the user from logging keystrokes or reading back images from 
that X server. Using <code>xauth</code>, one can obtain 
&ldquo;untrusted&rdquo; X authentication keys that prevent such 
exploits, but unfortunately, those untrusted keys also disallow access 
to the 3D hardware.  Thus, it is necessary to grant full, trusted access 
to the 3D X server for any users that will need to run VirtualGL.  
Unless you fully trust the users to whom you are granting this access, 
then you should avoid logging in locally to the 3D X server 
(particularly as root) unless absolutely necessary.</p>

<p>This section will explain how to configure a VirtualGL server such that 
selected users can run VirtualGL, even if the server is sitting at the 
login prompt.</p>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Shut down the display manager:
        <dl class="Description">
            <dt class="Description-3 Description">Ubuntu Linux servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/gdm&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">Ubuntu Linux servers running LightDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
service&nbsp;lightdm&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">SuSE Linux servers</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/xdm&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">Red Hat/Fedora Linux servers with SysV init</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
init&nbsp;3
</pre>

            </dd>
            <dt class="Description-3 Description">Red Hat/Fedora Linux servers with systemd</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
systemctl&nbsp;stop&nbsp;gdm.service
</pre>

            </dd>
            <dt class="Description-3 Description">Linux servers running MDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/mdm&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris 10 servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
svcadm&nbsp;disable&nbsp;gdm2-login
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris 11/OpenSolaris servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
svcadm&nbsp;disable&nbsp;gdm
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris servers running dtlogin</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/dtlogin&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">FreeBSD servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/usr/local/etc/rc.d/gdm&nbsp;stop
</pre>

            </dd>
            <dt class="Description-3 Description">FreeBSD servers running KDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/usr/local/kde4/etc/rc.d/kdm4&nbsp;stop
</pre>

            </dd>
        </dl>
    </li>
    <li class="Ordered-1 Ordered">
        Log in as root from the text console (or remotely using SSH.)
    </li>
    <li class="Ordered-1 Ordered">
        Run
<pre class="verbatim">
/opt/VirtualGL/bin/vglserver_config
</pre>

    </li>
    <li class="Ordered-1 Ordered">
        Select option 1 
        (<code>Configure&nbsp;server&nbsp;for&nbsp;use&nbsp;with&nbsp;VirtualGL&nbsp;in&nbsp;GLX&nbsp;mode</code>.)
    </li>
    <li class="Ordered-1 Ordered">

<pre class="verbatim">
Restrict&nbsp;3D&nbsp;X&nbsp;server&nbsp;access&nbsp;to&nbsp;vglusers&nbsp;group&nbsp;(recommended)?
[Y/n]
</pre>

        <dl class="Description">
            <dt class="Description-3 Description">Yes</dt>
            <dd class="Description-3 Description">
                Only users in the <code>vglusers</code> group can use VirtualGL (the 
                configuration script will create the <code>vglusers</code> group if it 
                doesn&rsquo;t already exist.)  This is the most secure option, since it 
                prevents any users outside of the <code>vglusers</code> group from 
                accessing (and thus exploiting) the 3D X server.
            </dd>
            <dt class="Description-3 Description">No</dt>
            <dd class="Description-3 Description">
                VirtualGL can be used by any user that successfully logs into the 
                VirtualGL server.  The 3D X server can also be accessed (and potentially 
                exploited) by any user who is logged into the VirtualGL server.  If you 
                choose this option, it is recommended that you also disable the XTEST 
                extension (see below.)
            </dd>
        </dl>
    </li>
    <li class="Ordered-1 Ordered">

<pre class="verbatim">
Restrict&nbsp;framebuffer&nbsp;device&nbsp;access&nbsp;to&nbsp;vglusers&nbsp;group&nbsp;(recommended)?
[Y/n]
</pre>

        <dl class="Description">
            <dt class="Description-3 Description">Yes</dt>
            <dd class="Description-3 Description">
                Only users in the <code>vglusers</code> group can run OpenGL 
                applications on the VirtualGL server (the configuration script will 
                create the <code>vglusers</code> group if it doesn&rsquo;t already 
                exist.)  This limits the possibility that an unauthorized user could 
                snoop the 3D framebuffer device(s) and thus see (or alter) the output of 
                a 3D application that is being used with VirtualGL.
            </dd>
            <dt class="Description-3 Description">No</dt>
            <dd class="Description-3 Description">
                Any authenticated user can run OpenGL applications on the VirtualGL 
                server.  If it is necessary for users outside of the 
                <code>vglusers</code> group to log in locally to this server and run 
                OpenGL applications, then this option must be selected.
            </dd>
        </dl>
    </li>
    <li class="Ordered-1 Ordered">

<pre class="verbatim">
Disable&nbsp;XTEST&nbsp;extension&nbsp;(recommended)?
[Y/n]
</pre>

        <dl class="Description">
            <dt class="Description-3 Description">Yes</dt>
            <dd class="Description-3 Description">
                Disabling XTEST will not prevent a user from logging keystrokes or 
                reading images from the 3D X server, but if a user has access to the 3D 
                X server, disabling XTEST will prevent them from inserting keystrokes or 
                mouse events and thus hijacking local X sessions on that X server.
                <div class="important"><p class="important">
                If you are using GDM 2.14 through 2.20, it will be necessary to run <code>gdmsetup</code> and manually add an argument of <code>-tst</code> to the X server command line to disable XTEST for the first time.  After this, <code>vglserver_config</code> should be able to disable and enable XTEST properly.
                </p></div>
                <div class="important"><p class="important">
                GDM 2.22 and later no longer provide a means of editing the X server command line, so disabling XTEST will not work.  The only known alternative as of this writing is to use a different display manager.
                </p></div>
            </dd>
            <dt class="Description-3 Description">No</dt>
            <dd class="Description-3 Description">
                <code>x11vnc</code> and <code>x0vncserver</code> both require XTEST, so 
                if you need to attach a VNC server to the 3D X server, then it is 
                necessary to answer &ldquo;No&rdquo; (and thus leave XTEST enabled.)
            </dd>
        </dl>
    </li>
    <li class="Ordered-1 Ordered">
        If you chose to restrict X server or framebuffer device access to the 
        <code>vglusers</code> group, then edit <code>/etc/group</code> and add 
        <code>root</code> to the <code>vglusers</code> group.  If you choose, 
        you can also add additional users to the group at this time.  Note that 
        any user you add to <code>vglusers</code>	must log out and back in again 
        before their new group permissions will take effect.
    </li>
    <li class="Ordered-1 Ordered">
        Restart the display manager:
        <dl class="Description">
            <dt class="Description-3 Description">Ubuntu Linux servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/gdm&nbsp;start
</pre>

            </dd>
            <dt class="Description-3 Description">Ubuntu Linux servers running LightDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
service&nbsp;lightdm&nbsp;start
</pre>

            </dd>
            <dt class="Description-3 Description">SuSE Linux servers</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/xdm&nbsp;start
</pre>

        Red Hat/Fedora Linux servers with SysV init:: 
<pre class="verbatim">
init&nbsp;5
</pre>

            </dd>
            <dt class="Description-3 Description">Red Hat/Fedora Linux servers with systemd</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
systemctl&nbsp;start&nbsp;gdm.service
</pre>

            </dd>
            <dt class="Description-3 Description">Linux servers running MDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/mdm&nbsp;start
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris 10 servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
svcadm&nbsp;enable&nbsp;gdm2-login
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris 11/OpenSolaris servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
svcadm&nbsp;enable&nbsp;gdm
</pre>

            </dd>
            <dt class="Description-3 Description">Solaris servers running dtlogin</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/etc/init.d/dtlogin&nbsp;start
</pre>

            </dd>
            <dt class="Description-3 Description">FreeBSD servers running GDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/usr/local/etc/rc.d/gdm&nbsp;start
</pre>

            </dd>
            <dt class="Description-3 Description">FreeBSD servers running KDM</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
/usr/local/kde4/etc/rc.d/kdm4&nbsp;start
</pre>

            </dd>
        </dl>
    </li>
</ol>


<h3 id="hd006002001">Sanity Check</h3>

<p>To verify that the application server is ready to run VirtualGL, log out 
of the server, log back into the server using SSH, and execute the 
following commands in the SSH session:</p>

<dl class="Description">
    <dt class="Description-1 Description">If you restricted 3D X server access to <code>vglusers</code></dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
xauth&nbsp;merge&nbsp;/etc/opt/VirtualGL/vgl_xauth_key
xdpyinfo&nbsp;-display&nbsp;:0
/opt/VirtualGL/bin/glxinfo&nbsp;-display&nbsp;:0&nbsp;-c
</pre>

        <div class="important"><p class="important">
        NOTE: <code>xauth</code> and <code>xdpyinfo</code> are in <code>/usr/openwin/bin</code> on Solaris systems.
        </p></div>
    </dd>
    <dt class="Description-1 Description">If you did not restrict 3D X server access</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
xdpyinfo&nbsp;-display&nbsp;:0
/opt/VirtualGL/bin/glxinfo&nbsp;-display&nbsp;:0&nbsp;-c
</pre>

    </dd>
</dl>

<p>Both commands should output a list of visuals and should complete with 
no errors.  If you chose to disable the XTEST extension, then check the 
output of <code>xdpyinfo</code> to verify that <code>XTEST</code> does 
not show up in the list of extensions.</p>

<p>You should also examine the output of <code>glxinfo</code> to ensure 
that at least one of the visuals is 24-bit or 32-bit TrueColor and has 
Pbuffer support (the latter is indicated by a &ldquo;P&rdquo; in the 
last column.)  Example:</p>

<pre class="verbatim">
&nbsp;&nbsp;&nbsp;&nbsp;visual&nbsp;&nbsp;x&nbsp;&nbsp;&nbsp;bf&nbsp;lv&nbsp;rg&nbsp;d&nbsp;st&nbsp;&nbsp;colorbuffer&nbsp;&nbsp;ax&nbsp;dp&nbsp;st&nbsp;accumbuffer&nbsp;&nbsp;ms&nbsp;&nbsp;cav&nbsp;&nbsp;drw
&nbsp;&nbsp;id&nbsp;dep&nbsp;cl&nbsp;sp&nbsp;&nbsp;sz&nbsp;l&nbsp;&nbsp;ci&nbsp;b&nbsp;ro&nbsp;&nbsp;r&nbsp;&nbsp;g&nbsp;&nbsp;b&nbsp;&nbsp;a&nbsp;F&nbsp;bf&nbsp;th&nbsp;cl&nbsp;&nbsp;r&nbsp;&nbsp;g&nbsp;&nbsp;b&nbsp;&nbsp;a&nbsp;ns&nbsp;b&nbsp;eat&nbsp;&nbsp;typ
------------------------------------------------------------------------------
0x151&nbsp;24&nbsp;tc&nbsp;&nbsp;0&nbsp;&nbsp;32&nbsp;&nbsp;0&nbsp;r&nbsp;&nbsp;y&nbsp;&nbsp;.&nbsp;&nbsp;8&nbsp;&nbsp;8&nbsp;&nbsp;8&nbsp;&nbsp;0&nbsp;.&nbsp;&nbsp;4&nbsp;24&nbsp;&nbsp;8&nbsp;16&nbsp;16&nbsp;16&nbsp;16&nbsp;&nbsp;0&nbsp;0&nbsp;None&nbsp;PXW
</pre>

<p>If none of the visuals has Pbuffer support, then this is most likely 
because there is no 3D acceleration, which is most likely because the 
correct 3D drivers are not installed (or are misconfigured.)  Lack of 3D 
acceleration is also typically indicated by the word &ldquo;Mesa&rdquo; 
in the client GLX vendor string and/or the OpenGL vendor string, and the 
words &ldquo;Software Rasterizer&rdquo; in the OpenGL renderer string.</p>



<h2 id="hd006003">6.3&nbsp;Using VirtualGL with Multiple GPUs</h2>

<p>VirtualGL can redirect the OpenGL commands from a 3D application to any 
GPU in the server machine.  In order for this to work, however, all of 
the GPUs must be attached to different screens on the same X server or 
to different X servers.  Attaching them to different screens is the 
easiest and most common approach, and this allows the GPUs to be 
individually addressed by setting <code>VGL_DISPLAY</code> to (or 
invoking <code>vglrun&nbsp;-d</code> with) <code>:0.0</code>, 
<code>:0.1</code>, <code>:0.2</code>, etc.  If the GPUs are attached to 
different X servers, then they can be individually addressed by setting 
<code>VGL_DISPLAY</code> to (or invoking <code>vglrun&nbsp;-d</code> 
with) <code>:0.0</code>, <code>:1.0</code>, <code>:2.0</code>, etc.</p>



<h2 id="hd006004">6.4&nbsp;SSH Server Configuration</h2>

<p>The application server&rsquo;s SSH daemon should have the 
<code>X11Forwarding</code> option enabled and the <code>UseLogin</code> 
option disabled.  This is configured in <code>sshd_config</code>, which 
is usually located under <code>/etc/ssh</code>.</p>



<h2 id="hd006005">6.5&nbsp;Un-Configuring the Server</h2>

<p>You can use the <code>vglserver_config</code> script to restore the 
security settings that were in place before VirtualGL was installed.  
Option 2 
(<code>Unconfigure&nbsp;server&nbsp;for&nbsp;use&nbsp;with&nbsp;VirtualGL&nbsp;in&nbsp;GLX&nbsp;mode</code>) 
will remove any shared access to the 3D X server and thus prevent 
VirtualGL from accessing the 3D hardware in that manner.  Additionally, 
this option will re-enable the XTEST extension on the 3D X server and 
will restore the framebuffer device permissions to their default (by 
default, only root or the user that is currently logged into the 
application server locally can access the framebuffer devices.)</p>

<div class="important"><p class="important">
NOTE: Unconfiguring the server does not remove the <code>vglusers</code> group.
</p></div>

<p>After selecting Option 2, you must restart the display manager before 
the changes will take effect.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd007"><a name="file007"></a>7&nbsp;Configuring a Windows Machine as a VGL Transport Client</h1>

<p>VirtualGL has the ability to take advantage of the MIT-SHM extension in 
Cygwin/X to accelerate image drawing on Windows.  This can significantly 
improve the overall performance of the VirtualGL pipeline when running 
over a local-area network.</p>

<p>To enable MIT-SHM in Cygwin/X:</p>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Open a Cygwin Bash shell
    </li>
    <li class="Ordered-1 Ordered">
        Run <code>cygserver-config</code>
    </li>
    <li class="Ordered-1 Ordered">
        Answer &ldquo;yes&rdquo; when asked &ldquo;Do you want to install 
        cygserver as service?&rdquo;
    </li>
    <li class="Ordered-1 Ordered">
        From a Windows (not Cygwin) command prompt, run 
        <code>net&nbsp;start&nbsp;cygserver</code>
    </li>
    <li class="Ordered-1 Ordered">
        Add <code>server</code> to the <code>CYGWIN</code> system environment 
        variable (create this environment variable if it doesn&rsquo;t already 
        exist)
    </li>
    <li class="Ordered-1 Ordered">
        Start or re-start Cygwin/X
    </li>
    <li class="Ordered-1 Ordered">
        Run <code>xdpyinfo</code> and verify that <code>MIT-SHM</code> appears 
        in the list of  X extensions
    </li>
</ol>

<p><br /></p>

<hr class="break" />



<h1 id="hd008"><a name="file008"></a>8&nbsp;Using VirtualGL with the VGL Transport</h1>

<p><a name="VGL_Transport_Usage"></a></p>


<h3 id="hd008000001">Advantages of the VGL Transport</h3>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        Seamless windows; every application window appears as a separate window 
        on the user&rsquo;s desktop
    </li>
    <li class="Itemize-1 Itemize asterisk">
        Supports stereographic rendering (see requirements in Sections 
        <a href="#Stereo_Requirements" class="ref">4.4</a> and 
        <a href="#Overlay_Requirements" class="ref">4.5</a>)
    </li>
    <li class="Itemize-1 Itemize asterisk">
        Consumes less memory and CPU time on the server, since the 2D (X11) 
        rendering occurs on the client machine
    </li>
</ul>



<h3 id="hd008000002">Disadvantages of the VGL Transport</h3>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        The VGL Transport is designed to be used with remote X servers, and thus 
        it relies on the chatty remote X11 protocol to send the 2D elements of 
        the application&rsquo;s GUI to the user&rsquo;s desktop.  As a result, 
        the VGL Transport is not recommended for use on high-latency or 
        low-bandwidth networks
    </li>
    <li class="Itemize-1 Itemize asterisk">
        No collaboration features
    </li>
    <li class="Itemize-1 Itemize asterisk">
        The client is not stateless.  As with any remote X11 environment, if the 
        network connection drops, then the application will exit
    </li>
</ul>



<h2 id="hd008001">8.1&nbsp;VGL Transport with X11 Forwarding</h2>

<p><a name="X11_Forwarding"></a></p>

<p>This mode is recommended for use only on secure local-area networks.  
The X11 traffic is encrypted, but the VGL Transport is left unencrypted 
to maximize performance.</p>


<h3 id="hd008001001">8.1.1&nbsp;Procedure</h3>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Start the X server if it isn&rsquo;t started already.<br /> <em>Mac 
        clients:</em> start the Mac X11 application or XQuartz.<br /> <em>Cygwin 
        clients:</em> start Cygwin/X.
    </li>
    <li class="Ordered-1 Ordered">
        Open a new terminal window.<br /> <em>Mac clients:</em> in the X11 
        application, start a new xterm [Command-N] if one isn&rsquo;t already 
        started.<br /> <em>Cygwin clients:</em> start a new xterm if one 
        isn&rsquo;t already started (right-click on the Cygwin/X taskbar icon, 
        then select <em>Applications&ndash;&gt;xterm</em>.)
    </li>
    <li class="Ordered-1 Ordered">
        In the same terminal/xterm window, open a Secure Shell (SSH) session 
        into the VirtualGL server:
<pre class="verbatim">
/opt/VirtualGL/bin/vglconnect&nbsp;{user}@{server}
</pre>

        Replace <em><code>{user}</code></em> with your username on the VirtualGL 
        server and <em><code>{server}</code></em> with the hostname or IP 
        address of that server.
    </li>
    <li class="Ordered-1 Ordered">
        In the SSH session, start a 3D application using VirtualGL:
<pre class="verbatim">
/opt/VirtualGL/bin/vglrun&nbsp;[vglrun&nbsp;options]&nbsp;{application_executable_or_script}&nbsp;{arguments}
</pre>

        Consult Chapter <a href="#Advanced_Configuration" class="ref">19</a> for 
        more information on <code>vglrun</code> command-line options.
    </li>
</ol>



<h2 id="hd008002">8.2&nbsp;VGL Transport with a Direct X11 Connection</h2>

<p><a name="Direct_X11_Connection"></a></p>

<p>As with the previous mode, this mode performs optimally on local-area 
networks.  However, it is less secure, since both the X11 traffic and 
the VGL Transport are unencrypted.  This mode is primarily useful in 
grid environments, in which you may not know ahead of time which server 
will execute a VirtualGL job.  It is assumed that the &ldquo;submit 
host&rdquo; (the machine into which you connect with SSH) and the 
&ldquo;execute hosts&rdquo; (the machines that will run VirtualGL jobs) 
share the same home directories and reside in the same domain.</p>

<div class="important"><p class="important">
Most newer Linux and Unix distributions ship with default settings that do not allow TCP connections into the X server.  Such systems cannot be used as clients with this procedure unless they are reconfigured to allow X11 TCP connections.
</p></div>


<h3 id="hd008002001">Procedure</h3>

<p>The procedure for this mode is identical to the procedure for the 
<a href="#X11_Forwarding">VGL Transport with X11 
forwarding</a><a name="idx0031"></a>, except that you should pass a 
<code>-x</code> argument to <code>vglconnect</code> when connecting to 
the server:</p>

<pre class="verbatim">
/opt/VirtualGL/bin/vglconnect&nbsp;-x&nbsp;{user}@{server}
</pre>



<h2 id="hd008003">8.3&nbsp;VGL Transport with X11 Forwarding and SSH Tunneling</h2>

<p><a name="SSH_Tunneling"></a></p>

<p>Both the VGL Transport and the X11 traffic are tunneled through SSH when 
using this mode, and thus it provides a completely secure solution.  It 
is also useful when either the VirtualGL server or the client machine 
are behind restrictive firewalls and only SSH connections are allowed 
through.  Using SSH tunneling on wide-area networks should not affect 
performance significantly.  However, using SSH tunneling on a local-area 
network can reduce the end-to-end performance of the VGL Transport by 
anywhere from 20-40%.</p>


<h3 id="hd008003001">Procedure</h3>

<p>The procedure for this mode is identical to the procedure for the 
<a href="#X11_Forwarding">VGL Transport with X11 
forwarding</a><a name="idx0032"></a>, except that you should pass a 
<code>-s</code> argument to <code>vglconnect</code> when connecting to 
the server:</p>

<pre class="verbatim">
/opt/VirtualGL/bin/vglconnect&nbsp;-s&nbsp;{user}@{server}
</pre>

<p><code>vglconnect</code> will make two SSH connections into the server, 
the first to find an open port on the server and the second to create 
the SSH tunnel for the VGL Transport and open the secure shell.  If you 
are not using an SSH agent to create password-less logins, then this 
mode will require you to enter your password twice.</p>

<p><code>vglconnect&nbsp;-s</code> can be used to create multi-layered SSH 
tunnels.  For instance, if the VirtualGL server is not directly 
accessible from the Internet, then you can run 
<code>vglconnect&nbsp;-s</code> on the client machine to connect to an 
SSH gateway server, then you can run <code>vglconnect&nbsp;-s</code> 
again on the gateway server to connect to the VirtualGL server 
(application server.)  Both the X11 traffic and the VGL Transport will 
be forwarded from the VirtualGL server through the gateway and to the 
client.</p>

<div class="figure">
<img src="sshtunnel.png" alt="sshtunnel" class="figure" id="imgid_7" name="imgid_7"/>
</div>



<h2 id="hd008004">8.4&nbsp;VGL Transport over Gigabit Networks</h2>

<p>When using the VGL Transport over Gigabit Ethernet or faster networks, 
it may be desirable to disable image compression.  This can be 
accomplished by passing an argument of <code>-c&nbsp;rgb</code> to 
<code>vglrun</code> or setting the <code>VGL_COMPRESS</code> environment 
variable to <code>rgb</code> on the VirtualGL server.  Disabling image 
compression will reduce VirtualGL&rsquo;s server and client CPU usage by 
50% or more, but the tradeoff is that it will also increase 
VirtualGL&rsquo;s network usage by a factor of 10 or more.  Thus, 
disabling image compression is not recommended unless you are using 
switched Gigabit Ethernet (or faster) infrastructure and have plenty of 
bandwidth to spare.</p>



<h2 id="hd008005">8.5&nbsp;VGL Transport with XDMCP</h2>

<div class="important"><p class="important">
XDMCP is very insecure and is not recommended as a means of running VirtualGL, in general.  This section is provided mainly for completeness and should not be construed as an endorsement of XDMCP.  In general, using an X proxy is a much better approach for accessing a remote desktop session on the 3D application server.
</p></div>

<p>Using the VGL Transport with XDMCP is conceptually similar to using the 
VGL Transport with a <a href="#Direct_X11_Connection">direct X11 
connection</a><a name="idx0033"></a>.  The major difference is that, 
rather than remotely displaying individual X windows to the 2D X server, 
XDMCP remotely displays a complete desktop session from the application 
server. X11 applications are launched inside of this remote desktop 
session rather than in a separate shell, so <code>vglconnect</code> 
cannot be used in this case.  Instead, it is necessary to start 
<code>vglclient</code> manually on the client machine.</p>


<h3 id="hd008005001">Procedure</h3>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Configure the server machine to accept XDMCP connections.  This may 
        require opening specific ports in its firewall.
    </li>
    <li class="Ordered-1 Ordered">
        Configure the client machine to make XDMCP connections.  This may 
        require enabling X11 TCP connections and opening specific ports in its 
        firewall.
    </li>
    <li class="Ordered-1 Ordered">
        Once you have established an XDMCP connection from the client to the 
        server, open a terminal inside the XDMCP session and type:
<pre class="verbatim">
xhost&nbsp;+LOCAL:
</pre>

        <div class="important"><p class="important">
        This grants access to the 2D X server for any user that is currently logged into the client machine.  This is not very secure, but neither is using XDMCP.  If you are concerned, then see below for a discussion of how to use <code>xauth</code> to provide 2D X server access in a slightly more secure manner.
        </p></div>
    </li>
    <li class="Ordered-1 Ordered">
        If you are using a Mac or Windows client, or if you are using a nested X 
        server (such as Xephyr or XNest) on a Linux/Unix client to make the 
        XDMCP connection, then the next step is easy.  Simply open a new 
        terminal/command prompt on the client machine, set the 
        <code>DISPLAY</code> environment variable to the display name of the X 
        server that is running the XDMCP session (usually <code>:0</code> or 
        <code>:1</code>), and type:
<pre class="verbatim">
vglclient&nbsp;-detach
</pre>

        You can now close the terminal/command prompt, if you wish.
    </li>
    <li class="Ordered-1 Ordered">
        If you are running a full-screen XDMCP session on a Linux/Unix client 
        (for instance, using GDM Chooser), then starting <code>vglclient</code> 
        is a bit trickier.  In this case, you can&rsquo;t open up a separate 
        terminal window on the client machine for the purposes of running 
        <code>vglclient</code>.  However, from inside of the XDMCP session, you 
        can open an SSH session back into the client machine.  In this SSH 
        session, set the <code>DISPLAY</code> environment variable to the 
        display name of the X server that is running the XDMCP session (usually 
        <code>:0</code> or <code>:1</code>), and type:
<pre class="verbatim">
vglclient&nbsp;-detach
</pre>

        You can now close the SSH session, if you wish.
    </li>
</ol>



<h3 id="hd008005002">Security</h3>

<p>Typing <code>xhost&nbsp;+LOCAL:</code> in step 3 above opens the 2D X 
server to all current users of the client machine.  This shouldn&rsquo;t 
pose any significant risk if the client is a Windows or a Mac machine.  
However, Linux/Unix clients might have multiple simultaneous users, so 
in these cases, it may be desirable to use a more secure method of 
granting access to the 2D X server.</p>

<p>Instead of typing <code>xhost&nbsp;+LOCAL:</code>, you can type the 
following:</p>

<pre class="verbatim">
xauth&nbsp;nextract&nbsp;-&nbsp;$DISPLAY&nbsp;|&nbsp;sed&nbsp;&quot;s/.*[&nbsp;]//g&quot;&nbsp;|&nbsp;xargs&nbsp;ssh&nbsp;{client}&nbsp;xauth&nbsp;add&nbsp;{display}&nbsp;.
</pre>

<p>where <em><code>{client}</code></em> is the hostname or IP address of 
the client machine and <em><code>{display}</code></em> is the display 
name of the 2D X server, from the point of view of the client machine 
(usually <code>:0</code> or <code>:1</code>).</p>

<p>This extracts the XAuth key for the 2D X server, then remotely adds it 
to the XAuth keyring on the client machine.</p>



<h2 id="hd008006">8.6&nbsp;The VirtualGL Client Application: Nuts and Bolts</h2>

<p>The VirtualGL Client application (<code>vglclient</code>) receives 
encoded and/or compressed images on a dedicated TCP socket, decodes 
and/or decompresses the images, and draws the images into the 
appropriate X window.  The <code>vglconnect</code> script wraps both 
<code>vglclient</code> and SSH to greatly simplify the process of 
creating VGL Transport connections.</p>

<p><code>vglconnect</code> invokes <code>vglclient</code> with an argument 
of <code>-detach</code>, which causes <code>vglclient</code> to 
completely detach from the console and run as a background daemon.  It 
will remain running silently in the background, accepting VGL Transport 
connections for the X server on which it was started, until that X 
server is reset or until the <code>vglclient</code> process is 
explicitly killed.  Logging out of the X server will reset the X server 
and thus kill all <code>vglclient</code> instances that are attached to 
it.  You can also explicitly kill all instances of 
<code>vglclient</code> running under your user account by invoking</p>

<pre class="verbatim">
vglclient&nbsp;-kill
</pre>

<p>(<code>vglclient</code> is installed in <code>/opt/VirtualGL/bin</code> 
by default.)</p>

<p><code>vglconnect</code> instructs <code>vglclient</code> to redirect all 
of its console output to a log file named 
<em><code>{home}</code></em><code>/.vgl/vglconnect-</code><em><code>{hostname}</code></em><code>-</code><em><code>{display}</code></em><code>.log</code>, 
where <em><code>{home}</code></em> is the path of the current 
user&rsquo;s home directory, <em><code>{hostname}</code></em> is the 
name of the computer running <code>vglconnect</code>, and 
<em><code>{display}</code></em> is the name of the current X display 
(read from the <code>DISPLAY</code> environment or passed to 
<code>vglconnect</code> using the <code>-display</code> argument.)  In 
the event that something goes wrong, this log file is the first place to 
check.</p>

<p>When <code>vglclient</code> successfully starts on a given X display, it 
stores its listener port number in a root window property on the X 
display.  If other <code>vglclient</code> instances attempt to start on 
the same X display, they read the X window property, determine that 
another <code>vglclient</code> instance is already running, and exit to 
allow the first instance to retain control. <code>vglclient</code> will 
clean up the X property under most circumstances, even if it is 
explicitly killed.  However, under rare circumstances (if sent a SIGKILL 
signal on Unix, for instance), a <code>vglclient</code> instance may 
exit uncleanly and leave the X property set.  In these cases, it may be 
necessary to add an argument of <code>-force</code> to 
<code>vglconnect</code> the next time you use it. This tells 
<code>vglconnect</code> to start a new <code>vglclient</code> instance, 
regardless of whether <code>vglclient</code> thinks that there is 
already an instance running on this X display.  Alternately, you can 
simply reset your X server to clear the orphaned X window property.</p>


<h3 id="hd008006001">8.6.1&nbsp;The VirtualGL Client and Firewalls</h3>

<p>To retain compatibility with previous versions of VirtualGL, the first 
<code>vglclient</code> instance on a given machine will attempt to 
listen on port 4242 for unencrypted connections and 4243 for SSL 
connections (if VirtualGL was built with OpenSSL support.)  If it fails 
to obtain one of those ports, because another application or another 
<code>vglclient</code> instance is already using them, then 
<code>vglclient</code> will try to obtain a free port in the range of 
4200-4299. Failing that, it will request a free port from the operating 
system.</p>

<p>In a nutshell: if you only ever plan to run one X server at a time on 
your client machine, which means that you&rsquo;ll only ever need one 
instance of <code>vglclient</code> at a time, then it is sufficient to 
open inbound port 4242 (and 4243 if you plan to use SSL) in your client 
machine&rsquo;s firewall.  If you plan to run multiple X servers on your 
client machine, which means that you will need to run multiple 
<code>vglclient</code> instances, then you may wish to open ports 
4200-4299.  Similarly, if you are running <code>vglclient</code> on a 
multi-user X proxy server that has a firewall, then you may wish to open 
ports 4200-4299 in the server&rsquo;s firewall.  Opening ports 4200-4299 
will accommodate up to 100 separate <code>vglclient</code> instances (50 
if OpenSSL support is enabled.)  More instances than that cannot be 
accommodated on a firewalled machine, unless the firewall is able to 
create rules based on application executables instead of listening ports.</p>

<p>Note that it is not necessary to open any inbound ports in the firewall 
to use the VGL Transport with <a href="#SSH_Tunneling">SSH 
Tunneling</a><a name="idx0034"></a>.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd009"><a name="file009"></a>9&nbsp;Using VirtualGL with X Proxies Such as VNC</h1>

<p><a name="X11_Proxy_Usage"></a></p>

<p>The VGL Transport is a good solution for using VirtualGL over a fast 
network.  However, the VGL Transport is not generally suitable for 
high-latency or low-bandwidth networks, due to its reliance on the X11 
protocol to send the non-3D elements of the 3D application&rsquo;s GUI.  
The VGL Transport also requires an X server to be running on the client 
machine, which makes it generally more difficult to deploy and use on 
Windows clients. VirtualGL can be used with an &ldquo;X proxy&rdquo; to 
overcome these limitations.  An X proxy acts as a virtual X server, 
receiving X11 commands from the application (and from VirtualGL), 
rendering the X11 commands into images, compressing the resulting 
images, and sending the compressed images over the network to a client 
or clients.  X proxies perform well on all types of networks, including 
high-latency and low-bandwidth networks.  They often provide rudimentary 
collaboration capabilities, allowing multiple clients to simultaneously 
view the same X session and pass around control of the keyboard and 
mouse.  X proxies are also stateless, meaning that the client can 
disconnect and reconnect at will from any machine on the network, and 
the 3D application will remain running on the server.</p>

<p>Since VirtualGL is sending rendered 3D images to the X proxy at a very 
fast rate, the proxy must be able to compress the images very quickly in 
order to keep up.  Unfortunately, however, most X proxies can&rsquo;t.  
They simply aren&rsquo;t designed to compress, with any degree of 
performance, the large and complex images generated by 3D applications.  
Therefore, the VirtualGL Project provides an optimized X proxy called 
&ldquo;TurboVNC&rdquo;, a variant of 
<span class="remote"><a href="http://www.tightvnc.com" class="remote">TightVNC</a></span><a name="idx0035"></a> 
that is designed specifically to achieve high levels of performance with 
3D applications running in VirtualGL.  More information about TurboVNC, 
including instructions for using it with VirtualGL, can be found in the 
TurboVNC User&rsquo;s Guide.</p>

<p>Many other X proxy solutions work well with VirtualGL, and some of these 
solutions provide compelling features (seamless windows, for instance, 
or session management), but none of these X proxies matches the 
performance of TurboVNC, as of this writing.</p>


<h2 id="hd009001">9.1&nbsp;Using VirtualGL with an X Proxy on the Same Server</h2>

<p><a name="X11_Proxy_Usage_Local"></a></p>

<p>The most common (and optimal) way to use VirtualGL with an X proxy is to 
set up both on the same server.  This allows VirtualGL to send its 
rendered 3D images to the X proxy through shared memory rather than 
sending them over a network.</p>

<div class="figure">
<img src="x11transport.png" alt="x11transport" class="figure" id="imgid_8" name="imgid_8"/>
</div>

<p>With this configuration, you can usually invoke</p>

<pre class="verbatim">
/opt/VirtualGL/bin/vglrun&nbsp;{application_executable_or_script}
</pre>

<p>from a terminal inside of the X proxy session, and it will &ldquo;just 
work.&rdquo; VirtualGL reads the value of the <code>DISPLAY</code> 
environment variable to determine whether to enable the X11 Transport by 
default.  If <code>DISPLAY</code> begins with a colon 
(&ldquo;<code>:</code>&rdquo;) or with &ldquo;<code>unix:</code>&rdquo;, 
then VirtualGL will assume that the X connection is local and will 
enable the X11 Transport as the default.  In some cases, however, the 
<code>DISPLAY</code> environment variable in the X proxy session may not 
begin with a colon or &ldquo;<code>unix:</code>&rdquo;.  In these cases, 
it is necessary to manually enable the X11 Transport by setting the 
<code>VGL_COMPRESS</code> environment variable to <code>proxy</code> or 
by passing an argument of <code>-c&nbsp;proxy</code> to 
<code>vglrun</code>.</p>



<h2 id="hd009002">9.2&nbsp;Using VirtualGL with an X Proxy on a Different Machine</h2>

<p><a name="X11_Proxy_Usage_Remote"></a></p>

<div class="figure">
<img src="vgltransportservernetwork.png" alt="vgltransportservernetwork" class="figure" id="imgid_9" name="imgid_9"/>
</div>

<p>If the X proxy and VirtualGL are running on different servers, then it 
is desirable to use the VGL Transport to send images from the VirtualGL 
server to the X proxy.  It is also desirable to disable image 
compression in the VGL Transport.  Otherwise, the images would have to 
be compressed by the VirtualGL server, decompressed by the VirtualGL 
Client, then recompressed by the X proxy, which is a waste of CPU 
resources.  However, sending images uncompressed over a network requires 
a fast network (generally, Gigabit Ethernet or faster), so there needs 
to be a fast link between the VirtualGL server and the X proxy server 
for this procedure to perform well.</p>

<p>The procedure for using the VGL Transport to display 3D applications 
from a VirtualGL server to a remote X proxy is the same as the 
<a href="#X11_Forwarding">procedure</a><a name="idx0036"></a> for using 
the VGL Transport to display 3D applications from a VirtualGL server to 
a remote 2D X server, with the following exceptions:</p>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        The &ldquo;client&rdquo; in this case is really the X proxy server.
    </li>
    <li class="Ordered-1 Ordered">
        The &ldquo;X server&rdquo; is really the X proxy.
    </li>
    <li class="Ordered-1 Ordered">
        It is recommended that you disable image compression in the VGL 
        Transport by either setting the <code>VGL_COMPRESS</code> environment 
        variable to <code>rgb</code> or passing an argument of 
        <code>-c&nbsp;rgb</code> to <code>vglrun</code> when launching 
        VirtualGL. Otherwise, VirtualGL will detect that the connection to the X 
        server is remote, and it will automatically try to enable JPEG 
        compression.
    </li>
</ol>

<p><br /></p>

<hr class="break" />



<h1 id="hd0010"><a name="file010"></a>10&nbsp;Support for the X Video Extension</h1>

<p><a name="X_Video_Support"></a></p>

<p>The X Video extension allows applications to pre-encode or pre-compress 
images and send them through the X server to the graphics adapter, which 
presumably has on-board video decoding capabilities.  This approach 
greatly reduces the amount of CPU resources used by the X server, which 
can be beneficial if the X server is running on a different machine than 
the application.</p>

<p>In the case of VirtualGL, what this means is that the VirtualGL client 
machine no longer has to decode or decompress images from the 3D 
application server. It can simply pass the images along to the graphics 
adapter for decoding.</p>

<p>VirtualGL supports the X Video extension in two ways:</p>


<h2 id="hd0010001">10.1&nbsp;The VGL Transport with YUV Encoding</h2>

<p>Setting the <code>VGL_COMPRESS</code> environment variable to 
<code>yuv</code> or passing an argument of <code>-c&nbsp;yuv</code> to 
<code>vglrun</code> enables the VGL Transport with YUV encoding.  When 
this mode is enabled, VirtualGL encodes images as YUV420P (a form of YUV 
encoding that uses 4X chrominance subsampling and separates Y, U, and V 
pixel components into separate image planes) instead of RGB or JPEG.  
The YUV420P images are sent to the VirtualGL Client, which draws them 
using the X Video extension.</p>

<p>On a per-frame basis, YUV encoding uses about half the server CPU time 
as JPEG compression and only slightly more server CPU time than RGB 
encoding.  On a per-frame basis, YUV encoding uses about 1/3 the client 
CPU time as JPEG compression and about half the client CPU time as RGB 
encoding.  YUV encoding also uses about half the network bandwidth (per 
frame) as RGB.</p>

<p>However, since YUV encoding uses 4X chrominance subsampling, the 
resulting images may contain some visible artifacts.  In particular, 
narrow, aliased lines and other sharp features may appear 
&ldquo;soft&rdquo;.</p>



<h2 id="hd0010002">10.2&nbsp;The XV Transport</h2>

<p>Setting the <code>VGL_COMPRESS</code> environment variable to 
<code>xv</code> or passing an argument of <code>-c&nbsp;xv</code> to 
<code>vglrun</code> enables the XV Transport.  The XV Transport is a 
special version of the X11 Transport that encodes images as YUV420P and 
draws them directly to the 2D X server using the X Video extension.  
This is mainly useful in conjunction with X proxies that support the X 
Video extension.  The idea is that, if the X proxy is going to have to 
transcode the image to YUV anyhow, VirtualGL may be faster at doing 
this, since it has a SIMD-accelerated YUV encoder.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0011"><a name="file011"></a>11&nbsp;Transport Plugins</h1>

<p><a name="Transport_Plugins"></a></p>

<p>VirtualGL 2.2 (and later) includes an API that allows you to write your 
own image transports.  Thus, you can use VirtualGL for doing split 
rendering and pixel readback but then use your own library for 
delivering the pixels to the client.</p>

<p>When the <code>VGL_TRANSPORT</code> environment variable (or the 
<code>-trans</code> option to <code>vglrun</code>) is set to 
<em><code>{t}</code></em>, then VirtualGL will look for a DSO (dynamic 
shared object) with the name 
<code>libtransvgl_</code><em><code>{t}</code></em><code>.so</code> in 
the dynamic linker path and will attempt to access a set of API 
functions from this library.  The functions that the plugin library must 
export are defined in <code>/opt/VirtualGL/include/rrtransport.h</code>, 
and an example of their usage can be found in 
<code>server/testplugin.cpp</code> and 
<code>server/testplugin2.cpp</code> in the VirtualGL source 
distribution.  The former wraps the VGL Transport as an image transport 
plugin, and the latter does the same for the X11 Transport.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0012"><a name="file012"></a>12&nbsp;Using VirtualGL with setuid/setgid Executables</h1>

<p><code>vglrun</code> can be used to launch either binary executables or 
shell scripts, but there are a few things to keep in mind when using 
<code>vglrun</code> to launch a shell script.  When you launch a shell 
script with <code>vglrun</code>, the VirtualGL faker library will be 
preloaded into every executable that the script launches. Normally this 
is innocuous, but if the script calls any executables that have the 
setuid and/or setgid permission bits set, then the dynamic linker will 
refuse to preload the VirtualGL faker library into those executables.  
One of the following warnings will be printed for each setuid/setgid 
executable that the script tries to launch:</p>

<dl class="Description">
    <dt class="Description-1 Description">Linux</dt>
    <dd class="Description-1 Description">
    </dd>
</dl>

<pre class="verbatim">
ERROR:&nbsp;ld.so:&nbsp;object&nbsp;'libvglfaker.so'&nbsp;from&nbsp;LD_PRELOAD&nbsp;cannot&nbsp;be&nbsp;preloaded:&nbsp;ignored.
</pre>

<pre class="verbatim">
ERROR:&nbsp;ld.so:&nbsp;object&nbsp;'libdlfaker.so'&nbsp;from&nbsp;LD_PRELOAD&nbsp;cannot&nbsp;be&nbsp;preloaded:&nbsp;ignored.
</pre>

<dl class="Description">
    <dt class="Description-1 Description">Solaris</dt>
    <dd class="Description-1 Description">
    </dd>
</dl>

<pre class="verbatim">
ld.so.1:&nbsp;warning:&nbsp;libvglfaker.so:&nbsp;open&nbsp;failed:&nbsp;No&nbsp;such&nbsp;file&nbsp;in&nbsp;secure&nbsp;directories
</pre>

<pre class="verbatim">
ld.so.1:&nbsp;warning:&nbsp;libdlfaker.so:&nbsp;open&nbsp;failed:&nbsp;No&nbsp;such&nbsp;file&nbsp;in&nbsp;secure&nbsp;directories
</pre>

<p>These are just warnings, and the setuid/setgid executables will continue 
to run (without VirtualGL preloaded into them.)  However, if you want to 
get rid of the warnings, an easy way to do so is to simply edit the 
application script and make it store the value of the 
<code>LD_PRELOAD</code> environment variable until right before the 
application executable is launched.  For instance, consider the 
following application script:</p>

<p>Initial contents of <code>application.sh</code>:</p>

<pre class="verbatim">
#!/bin/sh
some_setuid_executable
some_3D_application_executable
</pre>

<p>You could modify the script as follows:</p>

<pre class="verbatim">
#!/bin/sh
LD_PRELOAD_SAVE=$LD_PRELOAD
LD_PRELOAD=
export&nbsp;LD_PRELOAD

some_setuid_executable

LD_PRELOAD=$LD_PRELOAD_SAVE
export&nbsp;LD_PRELOAD

some_3D_application_executable
</pre>

<p>This procedure may be necessary to work around certain other interaction 
issues between VirtualGL and the launch scripts of specific 
applications.  See <a href="#Application_Recipes">Application 
Recipes</a><a name="idx0037"></a> for more details.</p>

<p>If the 3D application that you are intending to run in VirtualGL is 
itself a setuid/setgid executable, then further steps are required.  
Otherwise, the 3D application will launch without VirtualGL preloaded 
into it.  Forcing VirtualGL to be preloaded into setuid/setgid 
executables has security ramifications, so please be aware of these 
before you do it.  By applying one of the following workarounds, you are 
essentially telling the operating system that you trust the security and 
stability of VirtualGL as much as you trust the security and stability 
of the operating system.  While we&rsquo;re flattered, we&rsquo;re not 
sure that we&rsquo;re necessarily deserving of that accolade, so if you 
are in a security-critical environment, apply the appropriate level of 
paranoia here.</p>

<p><a name="setuid_linux"></a> To force VirtualGL to be preloaded into 
setuid/setgid executables on Linux, you have to first make sure that the 
faker libraries (<code>libvglfaker.so</code> and 
<code>libdlfaker.so</code>) are installed in the &ldquo;system&rdquo; 
library path (usually <code>/usr/lib</code>, <code>/usr/lib64</code>, 
<code>/usr/lib32</code>, or <code>/usr/lib/i386-linux-gnu</code>). Next, 
make <code>libvglfaker.so</code> and <code>libdlfaker.so</code> setuid 
executables.  To do this, run the following commands as root:</p>

<pre class="verbatim">
chmod&nbsp;u+s&nbsp;/usr/{lib}/libvglfaker.so
chmod&nbsp;u+s&nbsp;/usr/{lib}/libdlfaker.so
</pre>

<p>where <em><code>{lib}</code></em> is <code>lib</code>, 
<code>lib64</code>, <code>lib32</code>, or 
<code>lib/i386-linux-gnu</code>, depending on your system.</p>

<p>On Solaris, you can force VirtualGL to be preloaded into setuid/setgid 
executables by adding the VirtualGL library directories to the Solaris 
&ldquo;secure path.&rdquo;  Solaris keeps a tight lid on what goes into 
<code>/usr/lib</code> and <code>/lib</code>, and by default, it will 
only allow libraries in those paths to be preloaded into an executable 
that is setuid and/or setgid.  Generally, 3rd party packages are 
forbidden from installing anything into <code>/usr/lib</code> or 
<code>/lib</code>, but you can use the <code>crle</code> utility to add 
other directories to the operating system&rsquo;s list of secure paths.  
In the case of VirtualGL, you would execute one of the following 
commands (as root):</p>

<dl class="Description">
    <dt class="Description-1 Description">32-bit VirtualGL:</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
crle&nbsp;-u&nbsp;-s&nbsp;/opt/VirtualGL/lib32
</pre>

    </dd>
    <dt class="Description-1 Description">64-bit VirtualGL:</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
crle&nbsp;-64&nbsp;-u&nbsp;-s&nbsp;/opt/VirtualGL/lib64
</pre>

    </dd>
</dl>

<p><br /></p>

<hr class="break" />



<h1 id="hd0013"><a name="file013"></a>13&nbsp;Using VirtualGL with VirtualBox</h1>

<p>VirtualBox is an enterprise-class, open source virtualization solution 
provided by Oracle.  Since version 2.1.0, VirtualBox has provided 
support for hardware-accelerated OpenGL in Windows and Linux guests 
running on Windows, Mac/Intel, Linux, and Solaris/x86 hosts. 3D 
acceleration in VirtualBox is accomplished by installing a special 
driver in the guest that uses a subset of Chromium to transmit OpenGL 
calls through a local connection to the VirtualBox process running on 
the host.  When used in conjunction with VirtualGL on a Linux or 
Solaris/x86 host, this solution provides a means of displaying Windows 
3D applications remotely.</p>

<p>To use VirtualGL with VirtualBox, perform the following procedures:</p>


<h3 id="hd0013000001">Configuring the System</h3>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Launch VirtualBox and use the VirtualBox GUI to create and test your 
        virtual machine.
    </li>
    <li class="Ordered-1 Ordered">
        Follow the procedures outlined in the VirtualBox User&rsquo;s Manual to 
        enable 3D acceleration in the virtual machine.  Verify that 3D 
        acceleration works <em>without</em> VirtualGL before adding VirtualGL to 
        the mix.
    </li>
    <li class="Ordered-1 Ordered">
        Follow the procedure described in Chapter 
        <a href="#setuid_linux" class="ref">12</a> to make 
        <code>libvglfaker.so</code> and <code>libdlfaker.so</code> setuid 
        executables (Linux) or to add the VirtualGL library directory to the 
        list of secure paths (Solaris).
    </li>
</ol>



<h3 id="hd0013000002">Launching VirtualBox</h3>

<pre class="verbatim">
vglrun&nbsp;VirtualBox&nbsp;-startvm&nbsp;{VM&nbsp;name&nbsp;or&nbsp;UUID}
</pre>

<p>This should work on most systems.  It is known to work with VirtualBox 
4.1.8 and prior and with VirtualBox 4.2 and later on Linux.</p>

<div class="important"><p class="important">
With VirtualBox 4.1.10 and later 4.1.x versions, it is necessary to rename <code>/usr/lib/virtualbox/VBoxTestOGL</code> and execute <code>ln&nbsp;-fs&nbsp;/bin/true&nbsp;/usr/lib/virtualbox/VBoxTestOGL</code> in order to use those versions of VirtualBox with VirtualGL.
</p></div>



<h3 id="hd0013000003">NOTES</h3>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        You might want to temporarily enable profiling (add an argument of 
        <code>+pr</code> to <code>vglrun</code> above) or set the 
        <code>VGL_LOGO</code> environment variable to <code>1</code> in order to 
        verify that VirtualGL is loaded and working.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        It is necessary to start the virtual machine directly as described 
        above. Simply executing <code>vglrun&nbsp;VirtualBox</code> and using 
        the GUI to launch the VM does not work.  VirtualBox forks a separate 
        process for each VM, and the value of the <code>LD_PRELOAD</code> 
        environment variable from <code>vglrun</code> does not get propagated to 
        the VM process unless you start it directly.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        VirtualBox sends mainly uncompressed image updates to the X display, so 
        the 2D elements of the virtual machine&rsquo;s display will not perform 
        well over a remote X11 connection unless gigabit Ethernet (or faster) 
        and a <a href="#Direct_X11_Connection">direct X11 
        connection</a><a name="idx0038"></a> (<code>vglconnect&nbsp;-x</code>) 
        are used.  Using a high-performance X proxy (such as TurboVNC) is 
        generally preferred when remotely displaying VirtualBox using VirtualGL, 
        particularly on 100 Megabit and slower networks.
    </li>
</ul>

<p><br /></p>

<hr class="break" />



<h1 id="hd0014"><a name="file014"></a>14&nbsp;Using VirtualGL with VMWare Workstation</h1>

<p>VirtualGL can also be used with VMWare Workstation, and the concept is 
basically the same as that of VirtualBox.  As with VirtualBox, VMWare 
uses a special driver in the guest O/S to intercept the OpenGL commands 
and marshal them to the host O/S, where VirtualGL picks them up.</p>

<p>To use VirtualGL with VMWare Workstation, perform the following 
procedures:</p>


<h3 id="hd0014000001">Configuring the System</h3>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Launch VMWare and use the VMWare GUI to create and test your virtual 
        machine.
    </li>
    <li class="Ordered-1 Ordered">
        Follow the procedures outlined in the VMWare User&rsquo;s Manual to 
        enable 3D acceleration in the virtual machine.  Verify that 3D 
        acceleration works <em>without</em> VirtualGL before adding VirtualGL to 
        the mix.
    </li>
    <li class="Ordered-1 Ordered">
        Follow the procedure described in Chapter 
        <a href="#setuid_linux" class="ref">12</a> to make 
        <code>libvglfaker.so</code> and <code>libdlfaker.so</code> setuid 
        executables.
    </li>
</ol>



<h3 id="hd0014000002">Launching VMWare</h3>

<p>This has been tested with VMWare Workstation 9.</p>

<pre class="verbatim">
vglrun&nbsp;vmware&nbsp;-X&nbsp;{VM&nbsp;path}/{VM&nbsp;name}.vmx
</pre>



<h3 id="hd0014000003">NOTES</h3>

<p>The notes from the previous chapter apply to VMWare Workstation as well.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0015"><a name="file015"></a>15&nbsp;Other Application Recipes</h1>

<p><a name="Application_Recipes"></a></p>

<div class="table">
<table class="standard">
  <thead class="standard">
  <tr class="head ">
    <th class="head standard">Application</th>
    <th class="head standard">Versions Known to Require Recipe</th>
    <th class="head standard">Platform</th>
    <th class="head standard">Recipe</th>
    <th class="head standard">Notes</th>
  </tr>
  </thead>
  <tr class="standard">
    <td class="standard">Abaqus</td>
    <td class="standard">v6</td>
    <td class="standard">Linux</td>
    <td class="standard">It is necessary to add <br /><br /> <code>import&nbsp;os</code><br /> <code>os.environ['ABAQUS_EMULATE_OVERLAYS']&nbsp;=&nbsp;&quot;1&quot;</code> <br /><br /> to <code>/{abaqus_install_dir}/{abaqus_version}/site/abaqus_v6.env</code> to make Abaqus v6 work properly with VirtualGL if the 2D X server does not support transparent overlays.  If this is not done, then the application may fail to launch, fail to display the 3D pixels, or the 3D pixels may become corrupted whenever other windows obscure them.</td>
    <td class="standard">VirtualGL does not redirect the rendering of transparent overlays, since those cannot be rendered in a Pbuffer.  Thus, in order to use transparent overlays, the 2D X server must be able to render them, which is rarely the case for X proxies (see Section <a href="#overlays" class="ref">16.2</a> for more details.)  Setting <code>ABAQUS_EMULATE_OVERLAYS</code> to <code>1</code> causes the application to emulate overlay rendering instead of using actual transparent overlays.  This workaround is known to be necessary when running Abaqus 6.9 and 6.10 in VNC.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Abaqus</td>
    <td class="standard">v6</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;-nodl&nbsp;{abaqus_path}/abaqus</code></td>
    <td class="standard">User reports indicate that Abaqus 6.9 will not work properly if <code>libdlfaker.so</code> from VirtualGL is preloaded into it.  This may be true for other versions of Abaqus as well.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Cadence Allegro</td>
    <td class="standard">v16.5</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;+sync&nbsp;allegro</code></td>
    <td class="standard">Allegro relies on mixed X11/OpenGL rendering, and thus certain features (specifically the <code>pcb_cursor_infinite</code> cursor style) do not work properly unless <code>VGL_SYNC</code> is enabled.  If <code>VGL_SYNC</code> is not enabled, then the crosshairs may remain on the screen.  Since <code>VGL_SYNC</code> automatically enables the X11 transport and disables frame spoiling, it is highly recommended that you use an X proxy when <code>VGL_SYNC</code> is enabled. See Section <a href="#VGL_SYNC" class="ref">19.1</a> for further information.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Animator</td>
    <td class="standard">v4</td>
    <td class="standard">Linux</td>
    <td class="standard">Comment out the line that reads <br /><br /> <code>unsetenv&nbsp;LD_PRELOAD</code> <br /><br /> in the <code>a4</code> script, then launch Animator 4 using <br /><br /> <code>vglrun&nbsp;-ge&nbsp;a4</code> <br /><br /></td>
    <td class="standard">When the <code>a4</code> script unsets <code>LD_PRELOAD</code>, this prevents VirtualGL from being loaded into the application.  Animator 4 additionally checks the value of <code>LD_PRELOAD</code> and attempts to unset it from inside the application.  Using <code>vglrun&nbsp;-ge</code> to launch the application fools Animator 4 into thinking that <code>LD_PRELOAD</code> is unset.</td>
  </tr>
  <tr class="standard">
    <td class="standard">ANSA</td>
    <td class="standard">v12.1.0</td>
    <td class="standard">Linux</td>
    <td class="standard">Add <br /><br /> <code>LD_PRELOAD_SAVE=$LD_PRELOAD</code><br /> <code>export&nbsp;LD_PRELOAD=</code> <br /><br /> to the top of the <code>ansa.sh</code> script, then add <br /><br /> <code>export&nbsp;LD_PRELOAD=$LD_PRELOAD_SAVE</code> <br /><br /> just prior to the <code>${ANSA_EXEC_DIR}bin/ansa_linux${ext2}</code> line.</td>
    <td class="standard">The ANSA startup script directly invokes <code>/lib/libc.so.6</code> to query the glibc version.  Since the VirtualGL faker depends on libc, preloading VirtualGL when directly invoking <code>libc.so.6</code> creates an infinite loop. Thus, it is necessary to disable the preloading of VirtualGL in the application script and then re-enable it prior to launching the actual application.</td>
  </tr>
  <tr class="standard">
    <td class="standard">ANSYS HFSS, ANSYS ICEM CFD, Roxar RMS</td>
    <td class="standard">All</td>
    <td class="standard">Linux</td>
    <td class="standard">Set the <code>VGL_SPOILLAST</code> environment variable to <code>0</code> prior to launching the application with <code>vglrun</code></td>
    <td class="standard">These applications draw node highlighting and/or rubber banding directly to the front buffer.  In order for these front buffer operations to be displayed properly, it is necessary to use the &ldquo;spoil first&rdquo; frame spoiling algorithm whenever the application calls <code>glFlush()</code>.  See Section <a href="#VGL_SPOILLAST" class="ref">19.1</a> for further information.</td>
  </tr>
  <tr class="standard">
    <td class="standard">AutoForm</td>
    <td class="standard">v4.0x</td>
    <td class="standard">All</td>
    <td class="standard"><code>vglrun&nbsp;+sync&nbsp;xaf_</code><em><code>{version}</code></em></td>
    <td class="standard">AutoForm relies on mixed X11/OpenGL rendering, and thus certain features (particularly the &ldquo;Dynamic Section&rdquo; dialog and &ldquo;Export Image&rdquo; feature) do not work properly unless <code>VGL_SYNC</code> is enabled.  Since <code>VGL_SYNC</code> automatically enables the X11 transport and disables frame spoiling, it is highly recommended that you use an X proxy when <code>VGL_SYNC</code> is enabled. See Section <a href="#VGL_SYNC" class="ref">19.1</a> for further information.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Cedega</td>
    <td class="standard">v6.0.x</td>
    <td class="standard">Linux</td>
    <td class="standard">Add <br /><br /> <code>export&nbsp;LD_PRELOAD=libvglfaker.so</code> <br /><br /> to the top of <code>~/.cedega/.winex_ver/winex-{version}/bin/winex3</code>, then run Cedega as you would normally (without <code>vglrun</code>.)  Since <code>vglrun</code> is not being used, it is necessary to use environment variables or the VirtualGL Configuration dialog to modify VirtualGL&rsquo;s configuration.</td>
    <td class="standard">The actual binary (WineX) that uses OpenGL is buried beneath several layers of Python and shell scripts.  The <code>LD_PRELOAD</code> variable does not get propagated down from the initial shell that invoked <code>vglrun</code>.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Google Chrome/Chromium</td>
    <td class="standard">v31 and later</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;google-chrome&nbsp;--disable-gpu-sandbox</code><br /> or<br /> <code>vglrun&nbsp;chromium&nbsp;--disable-gpu-sandbox</code></td>
    <td class="standard">By default, Chrome/Chromium uses a separate process to perform 3D rendering (WebGL), and for reasons that are not yet fully understood, this breaks VirtualGL.  The <code>--disable-gpu-sandbox</code> option causes 3D rendering to be performed within the browser process.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Compiz</td>
    <td class="standard">All</td>
    <td class="standard">Linux</td>
    <td class="standard">Set the <code>VGL_WM</code> environment variable to <code>1</code> prior to launching the window manager with <code>vglrun</code>, or pass an argument of <code>+wm</code> to <code>vglrun</code>.</td>
    <td class="standard">See Section <a href="#VGL_WM" class="ref">19.1</a> for further information.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Heretic II</td>
    <td class="standard">All</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;heretic2&nbsp;+set&nbsp;vid_ref&nbsp;glx</code></td>
    <td class="standard"></td>
  </tr>
  <tr class="standard">
    <td class="standard">Intel OpenCL ICD</td>
    <td class="standard">All</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;-ld&nbsp;{path_to_Intel_OpenCL_libs}&nbsp;{application}</code></td>
    <td class="standard">The Intel OpenCL installable client driver (ICD) is linked with a run-time library search path (rpath) of <code>$ORIGIN</code>, which would normally have the same effect as adding the directory in which the ICD is installed (default: <code>/opt/intel/opencl/lib64</code> on 64-bit systems) to <code>LD_LIBRARY_PATH</code>.  However, when VirtualGL is interposing the <code>dlopen()</code> function (which it does by default), this causes the actual <code>dlopen()</code> system calls to come from <code>libdlfaker.so</code>, so <code>$ORIGIN</code> will resolve to the directory in which the VirtualGL faker libraries are installed.  This causes the <code>dlopen()</code> calls within the Intel ICD to fail, and because the ICD apparently does not check the return value of those calls, a segfault occurs.  The workaround is simply to add the Intel ICD library path to <code>LD_LIBRARY_PATH</code>, which is most easily accomplished with <code>vglrun&nbsp;-ld</code>.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Mathematica</td>
    <td class="standard">v7</td>
    <td class="standard">Linux</td>
    <td class="standard">Set the <code>VGL_ALLOWINDIRECT</code> environment variable to <code>1</code> prior to launching the application with <code>vglrun</code></td>
    <td class="standard">Mathematica 7 will not draw the axis numbers on 3D charts correctly unless it is allowed to create an indirect OpenGL context.  See Section <a href="#VGL_ALLOWINDIRECT" class="ref">19.1</a> for further information.</td>
  </tr>
  <tr class="standard">
    <td class="standard">MATLAB</td>
    <td class="standard">All</td>
    <td class="standard">Linux</td>
    <td class="standard"><code>vglrun&nbsp;/usr/local/MATLAB/{version}/bin/matlab&nbsp;-nosoftwareopengl</code></td>
    <td class="standard">MATLAB will automatically use its built-in (unaccelerated) OpenGL implementation if it detects that it is running in a remote display environment.  More specifically, it will always enable software OpenGL if the X server has an X extension called <code>VNC-EXTENSION</code>, which is the case with TurboVNC, TigerVNC, and RealVNC.</td>
  </tr>
  <tr class="standard">
    <td class="standard">Tecplot 360</td>
    <td class="standard">2011 and earlier</td>
    <td class="standard">Linux</td>
    <td class="standard">Set the <code>VGL_GLFLUSHTRIGGER</code> environment variable to <code>0</code> prior to launching the application with <code>vglrun</code></td>
    <td class="standard">When running in TurboVNC (using VirtualGL), flashing artifacts will be produced when the user zooms/pans/rotates the scene in Tecplot 360, unless VirtualGL is instructed not to use <code>glFlush()</code> as an end-of-frame trigger.  This has been fixed in Tecplot 2012 and later. See Section <a href="#VGL_GLFLUSHTRIGGER" class="ref">19.1</a> for further information.</td>
  </tr>
</table>
</div>


<p><br /></p>

<hr class="break" />



<h1 id="hd0016"><a name="file016"></a>16&nbsp;Advanced OpenGL Features</h1>

<p><a name="Advanced_OpenGL"></a></p>


<h2 id="hd0016001">16.1&nbsp;Stereographic Rendering</h2>

<p>Stereographic rendering is a feature of OpenGL that creates separate 
rendering buffers for the left and right eyes and allows the application 
to render a different image into each buffer.  How the stereo images are 
subsequently displayed depends on the particulars of the 3D hardware and 
the user&rsquo;s environment.  VirtualGL can support stereographic 
applications in one of two ways: (1) by sending the stereo image pairs 
to the client to be displayed in stereo by the client&rsquo;s GPU, or 
(2) by combining each stereo image pair into a single image that can be 
viewed with traditional anaglyphic 3D glasses or a passive stereo 
system, such as a 3D TV.</p>


<h3 id="hd0016001001">16.1.1&nbsp;Quad-Buffered Stereo</h3>

<p>The name &ldquo;quad-buffered&rdquo; stereo refers to the fact that 
OpenGL uses four buffers (left front, right front, left back, and right 
back) to support stereographic rendering with double buffering.  GPUs 
with quad-buffered stereo capabilities generally provide some sort of 
synchronization signal that can be used to control various types of 
active stereo 3D glasses.  Some also support &ldquo;passive 
stereo&rdquo;, which requires displaying the left and right eye buffers 
to different monitor outputs.  VirtualGL supports quad-buffered stereo 
by rendering the stereo images on the server and sending the image pairs 
across the network to be displayed on the client.</p>

<p>In most cases, VirtualGL does not require that a GPU be present in the 
client machine.  However, a GPU is required to display stereo image 
pairs, so one must be present in any client machine that will use 
VirtualGL&rsquo;s quad-buffered stereo feature.  Since the GPU is only 
being used to draw images, it need not necessarily be a high-end GPU.  
Generally, the least expensive GPU that has stereo capabilities will 
work fine in a VirtualGL client machine.  The VirtualGL server must also 
have a GPU that supports stereo, since this is the only way that 
VirtualGL can obtain a stereo Pbuffer.</p>

<p>When an application tries to render something in stereo, VirtualGL will 
default to using quad-buffered stereo rendering if the 2D X server 
supports OpenGL and has stereo visuals available (not currently 
supported in Cygwin/X.) Otherwise, VirtualGL will fall back to using 
anaglyphic stereo (see below.) It is usually necessary to explicitly 
enable stereo in the graphics driver configuration for both the client 
and server machines.  The 
<a href="#Troubleshooting">Troubleshooting</a><a name="idx0039"></a> 
section below lists a way to verify that both the 3D X server and the 2D 
X server have stereo visuals available.</p>

<p>In quad-buffered mode, VirtualGL reads back both the left and right eye 
buffers on the server and sends the contents as a pair of compressed 
images to the VirtualGL Client.  The VirtualGL Client then decompresses 
both images and draws them as a single stereo frame to the client 
machine&rsquo;s X display using <code>glDrawPixels()</code>.  It should 
thus be no surprise that enabling quad-buffered stereo in VirtualGL 
decreases performance by 50% or more and uses twice the network 
bandwidth to maintain the same frame rate as mono.</p>

<p>Quad-buffered stereo requires the VGL Transport.  Attempting to enable 
it with any other image transport will cause VGL to fall back to 
anaglyphic stereo mode.</p>



<h3 id="hd0016001002">16.1.2&nbsp;Anaglyphic Stereo</h3>

<p>Anaglyphic stereo is the type of stereographic display used by old 3D 
movies. It typically relies on a set of 3D glasses consisting of red 
transparency film over the left eye and cyan transparency film over the 
right eye, although green/magenta and blue/yellow schemes can be used as 
well.  To generate a 3D anaglyph, one color channel from the left eye 
buffer is combined with the other two color channels from the right eye 
buffer, thus allowing a single monographic image to contain stereo data.  
For instance, in the case of red/cyan, the red channel is taken from the 
left eye buffer, and the green and blue channels are taken from the 
right eye buffer.  From the point of view of VirtualGL, an anaglyphic 
image is the same as a monographic image, so anaglyphic stereo images 
can be sent using any image transport to any type of client, regardless 
of the client&rsquo;s capabilities.</p>

<p>VirtualGL uses anaglyphic stereo if it detects that an application has 
rendered something in stereo but quad-buffered stereo is not available, 
either because the client doesn&rsquo;t support it or because a 
transport other than the VGL Transport is being used.  Anaglyphic stereo 
provides a cheap and easy way to view stereographic applications in X 
proxies and on clients that do not support quad-buffered stereo.  
Additionally, anaglyphic stereo performs much faster than quad-buffered 
stereo, since it does not require sending twice the data to the client.</p>

<p>As with quad-buffered stereo, anaglyphic stereo requires that the 
VirtualGL server have stereo rendering capabilities.  However, 
anaglyphic stereo does not require any 3D rendering capabilities (stereo 
or otherwise) on the client machine.</p>



<h3 id="hd0016001003">16.1.3&nbsp;Passive Stereo</h3>

<p>As with anaglyphic stereo, passive stereo combines a stereographic image 
pair into a single image (a &ldquo;stereogram&rdquo;), and thus it can 
be used with any image transport.  However, unlike anaglyphic stereo, 
passive stereo must be used with specific display hardware, such as a 3D 
TV or monitor, that decodes the left and right eye images from the 
stereogram and sends them separately to a pair of 3D glasses (typically, 
this is accomplished by way of polarization.)</p>

<p>VirtualGL supports three methods of encoding stereograms:</p>

<dl class="Description">
    <dt class="Description-1 Description">Interleaved</dt>
    <dd class="Description-1 Description">
        The even rows of the stereogram are taken from the left eye image, and 
        the odd rows are taken from the right eye image.
    </dd>
    <dt class="Description-1 Description">Top/Bottom</dt>
    <dd class="Description-1 Description">
        The top half of the stereogram is taken from the left eye image, and the 
        bottom half is taken from the right eye image.  Both halves are 
        subsampled 2X vertically.
    </dd>
    <dt class="Description-1 Description">Side-by-Side</dt>
    <dd class="Description-1 Description">
        The left half of the stereogram is taken from the left eye image, and 
        the right half is taken from the right eye image.  Both halves are 
        subsampled 2X horizontally.
    </dd>
</dl>

<p>Most 3D TVs/monitors can be configured to decode at least one of these 
types of stereograms.  In order for this to work, however, the 3D 
drawing area must be full-screen.</p>



<h3 id="hd0016001004">16.1.4&nbsp;Selecting a Stereo Mode</h3>

<p>A particular stereo mode can be selected by setting the 
<code>VGL_STEREO</code> environment variable or by using the 
<code>-st</code> argument to <code>vglrun</code>.  See Section 
<a href="#VGL_STEREO" class="ref">19.1</a> for more details.</p>



<h2 id="hd0016002">16.2&nbsp;Transparent Overlays</h2>

<p><a name="overlays"></a></p>

<p>In the case of transparent overlays, VirtualGL completely bypasses its 
own GLX faker and uses indirect OpenGL rendering to draw to the 
transparent overlay using the 2D X server.  The underlay is still 
rendered on the 3D X server, read back, and sent to the 2D X server, as 
always.  Using indirect rendering to render the overlay is unfortunately 
necessary, because there is no reliable way to draw to an overlay using 
2D (X11) functions, there are severe performance issues (on some cards) 
with using <code>glDrawPixels()</code> to draw to the overlay, and there 
is no reasonable way to composite the overlay and underlay in a Pbuffer 
on the VirtualGL server.</p>

<p>The use of overlays is becoming more and more infrequent, and when they 
are used, it is generally only for drawing small, simple, static shapes 
and text. We have found that it is often faster to ship the overlay 
geometry over to the 2D X server rather than to render it as an image 
and send the image.  Thus, even if it were possible to implement 
overlays without using indirect rendering, it is likely that indirect 
rendering of overlays would still be the fastest approach for most 
applications.</p>

<p>As with quad-buffered stereo, overlays must be explicitly enabled in the 
graphics driver and X server configurations.  In the case of overlays, 
however, they need only be supported and enabled on the client machine 
and in the 2D X server.  Some graphics drivers are known to disallow 
using both quad-buffered stereo and overlays at the same time.  
Transparent overlays are not currently supported in Cygwin/X.</p>

<p>Indexed color (8-bit) overlays have been tested and are known to work 
with VirtualGL.  True color (24-bit) overlays work, in theory, but have 
not been tested.  Use <code>glxinfo</code> (see 
<a href="#Troubleshooting">Troubleshooting</a><a name="idx0040"></a> 
below) to verify whether your client&rsquo;s X display supports overlays 
and whether they are enabled.</p>



<h2 id="hd0016003">16.3&nbsp;Troubleshooting</h2>

<p><a name="Troubleshooting"></a></p>

<p>VirtualGL includes a modified version of <code>glxinfo</code> that can 
be used to determine whether or not the 2D and 3D X servers have stereo 
or overlay visuals enabled.</p>

<p>Run the following command sequence on the VirtualGL server to determine 
whether the 3D X server has a suitable visual for stereographic 
rendering:</p>

<pre class="verbatim">
xauth&nbsp;merge&nbsp;/etc/opt/VirtualGL/vgl_xauth_key
/opt/VirtualGL/bin/glxinfo&nbsp;-display&nbsp;:{n}&nbsp;-c&nbsp;-v
</pre>

<p>(where <code>{n}</code> is the display number of the 3D X server.)  One 
or more of the visuals should say &ldquo;stereo=1&rdquo; and should list 
&ldquo;Pbuffer&rdquo; as one of the &ldquo;Drawable Types.&rdquo;</p>

<p>Run the following command sequence on the VirtualGL server to determine 
whether the 2D X server has a suitable visual for stereographic 
rendering or transparent overlays.</p>

<pre class="verbatim">
/opt/VirtualGL/bin/glxinfo&nbsp;-v
</pre>

<p>In order to use stereo, one or more of the visuals should say 
&ldquo;stereo=1&rdquo;. In order to use transparent overlays, one or 
more of the visuals should say &ldquo;level=1&rdquo;, should list a 
&ldquo;Transparent Index&rdquo; (non-transparent visuals will say 
&ldquo;Opaque&rdquo; instead), and should have a class of 
&ldquo;PseudoColor.&rdquo;</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0017"><a name="file017"></a>17&nbsp;Performance Measurement</h1>

<p><a name="Perf_Measurement"></a></p>


<h2 id="hd0017001">17.1&nbsp;VirtualGL&rsquo;s Built-In Profiling System</h2>

<p>The easiest way to uncover bottlenecks in VirtualGL&rsquo;s image 
pipeline is to set the <code>VGL_PROFILE</code> environment variable to 
<code>1</code> on both server and client (passing an argument of 
<code>+pr</code> to <code>vglrun</code> on the server has the same 
effect.)  This will cause VirtualGL to measure and report the throughput 
of various stages in the pipeline.  For example, here are some 
measurements from a dual Pentium 4 server communicating with a Pentium 
III client on a 100 Megabit LAN:</p>

<dl class="Description">
    <dt class="Description-1 Description">Server</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
Readback&nbsp;&nbsp;&nbsp;-&nbsp;43.27&nbsp;Mpixels/sec&nbsp;-&nbsp;34.60&nbsp;fps
Compress&nbsp;0&nbsp;-&nbsp;33.56&nbsp;Mpixels/sec&nbsp;-&nbsp;26.84&nbsp;fps
Total&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;&nbsp;8.02&nbsp;Mpixels/sec&nbsp;-&nbsp;&nbsp;6.41&nbsp;fps&nbsp;-&nbsp;10.19&nbsp;Mbits/sec&nbsp;(18.9:1)
</pre>

    </dd>
    <dt class="Description-1 Description">Client</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
Decompress&nbsp;-&nbsp;10.35&nbsp;Mpixels/sec&nbsp;-&nbsp;&nbsp;8.28&nbsp;fps
Blit&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;35.75&nbsp;Mpixels/sec&nbsp;-&nbsp;28.59&nbsp;fps
Total&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;&nbsp;8.00&nbsp;Mpixels/sec&nbsp;-&nbsp;&nbsp;6.40&nbsp;fps&nbsp;-&nbsp;10.18&nbsp;Mbits/sec&nbsp;(18.9:1)
</pre>

    </dd>
</dl>

<p>The total throughput of the pipeline is 8.0 Megapixels/sec, or 6.4 
frames/sec, indicating that our frame is 8.0 / 6.4 = 1.25 Megapixels in 
size (a little less than 1280 x 1024 pixels.)  The readback and compress 
stages, which occur in parallel on the server, are obviously not slowing 
things down, and we&rsquo;re only using 1/10 of our available network 
bandwidth.  Looking at the client, however, we discover that its slow 
decompression speed (10.35 Megapixels/second) is the primary bottleneck.  
Decompression and blitting on the client cannot be done in parallel, so 
the aggregate performance is the harmonic mean of the decompression and 
blitting rates:  <em>[1/ (1/10.35 + 1/35.75)] = 8.0 Mpixels/sec</em>. In 
this case, we could improve the performance of the whole system by 
simply using a client with a faster CPU.</p>

<div class="important"><p class="important">
This example is meant to demonstrate how the client can sometimes be the primary impediment to VirtualGL&rsquo;s end-to-end performance.  Using &ldquo;modern&rdquo; hardware on both ends of the connection, VirtualGL can easily stream 50+ Megapixels/sec across a LAN, as of this writing.
</p></div>



<h2 id="hd0017002">17.2&nbsp;Frame Spoiling</h2>

<p><a name="Frame_Spoiling"></a></p>

<p>By default, VirtualGL will only send a frame to the client if the client 
is ready to receive it.  If VirtualGL detects that the application has 
finished rendering a new frame but there are already frames waiting in 
the queue to be processed, then those unprocessed frames are dropped 
(&ldquo;spoiled&rdquo;) and the new frame is promoted to the head of the 
queue.  This prevents a backlog of frames on the server, which would 
cause a perceptible delay in the responsiveness of interactive 
applications.  However, when running non-interactive applications, 
particularly benchmarks, frame spoiling should always be disabled.   
With frame spoiling disabled, the server will render frames only as 
quickly as VirtualGL can send those frames to the client, which will 
conserve server resources as well as allow OpenGL benchmarks to 
accurately measure the end-to-end performance of VirtualGL (assuming 
that the VGL Transport is used.)  With frame spoiling enabled, OpenGL 
benchmarks will report meaningless data, since the rate at which the 
server can render frames is decoupled from the rate at which VirtualGL 
can send those frames to the client.</p>

<p>In most X proxies (including VNC), there is effectively another layer of 
frame spoiling, since the rate at which the X proxy can send frames to 
the client is decoupled from the rate at which VirtualGL can draw images 
into the X proxy. Thus, even if frame spoiling is disabled in VirtualGL, 
OpenGL benchmarks will still report inaccurate data if they are run in 
such X proxies.  TCBench, described below, provides a limited solution 
to this problem.</p>

<p>To disable frame spoiling, set the <code>VGL_SPOIL</code> environment 
variable to <code>0</code> on the VirtualGL server or pass an argument 
of <code>-sp</code> to <code>vglrun</code>.  See Section 
<a href="#VGL_SPOIL" class="ref">19.1</a> for further information.</p>



<h2 id="hd0017003">17.3&nbsp;VirtualGL Diagnostic Tools</h2>

<p>VirtualGL includes several tools that can be useful in diagnosing 
performance problems with the system.</p>


<h3 id="hd0017003001">NetTest</h3>

<p>NetTest is a network benchmark that uses the same network I/O classes as 
VirtualGL.  It can be used to test the latency and throughput of any 
TCP/IP connection, with or without SSL encryption.  <code>nettest</code> 
is installed in <code>/opt/VirtualGL/bin</code> by default.  For Windows 
users, a native Windows version of NetTest is included in the 
&ldquo;VirtualGL-Utils&rdquo; package, which is distributed alongside 
VirtualGL.</p>

<p>To use NetTest, first start up the NetTest server on one end of the 
connection:</p>

<pre class="verbatim">
nettest&nbsp;-server&nbsp;[-ssl]
</pre>

<p>(Use <code>-ssl</code> if you want to test the performance of SSL 
encryption over this particular connection.  VirtualGL must have been 
compiled with OpenSSL support for this option to be available.)</p>

<p>Next, start the client on the other end of the connection:</p>

<pre class="verbatim">
nettest&nbsp;-client&nbsp;{server}&nbsp;[-ssl]
</pre>

<p>Replace <em><code>{server}</code></em> with the hostname or IP address 
of the machine on which the NetTest server is running.  (Use 
<code>-ssl</code> if the NetTest server is running in SSL mode.  
VirtualGL must have been compiled with OpenSSL support for this option 
to be available.)</p>

<p>The NetTest client will produce output similar to the following:</p>

<pre class="verbatim">
TCP&nbsp;transfer&nbsp;performance&nbsp;between&nbsp;localhost&nbsp;and&nbsp;{server}:

Transfer&nbsp;size&nbsp;&nbsp;1/2&nbsp;Round-Trip&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Throughput&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Throughput
(bytes)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(msec)&nbsp;&nbsp;&nbsp;&nbsp;(MBytes/sec)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(Mbits/sec)
1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.093402&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.010210&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.085651
2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.087308&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.021846&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.183259
4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.087504&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.043594&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.365697
8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.088105&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.086595&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.726409
16&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.090090&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.169373&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.420804
32&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.093893&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.325026&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.726514
64&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.102289&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.596693&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.005424
128&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.118493&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.030190&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;8.641863
256&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.146603&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.665318&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;13.969704
512&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.205092&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.380790&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;19.971514
1024&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.325896&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.996542&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;25.136815
2048&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.476611&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4.097946&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;34.376065
4096&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0.639502&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6.108265&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;51.239840
8192&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.033596&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.558565&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;63.405839
16384&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.706110&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;9.158259&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;76.825049
32768&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.089896&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;10.113608&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;84.839091
65536&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.909509&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;10.576174&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;88.719379
131072&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.453894&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;10.913319&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;91.547558
262144&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;22.616389&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.053931&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;92.727094
524288&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;44.882406&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.140223&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;93.450962
1048576&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;89.440702&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.180592&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;93.789603
2097152&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;178.536997&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.202160&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;93.970529
4194304&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;356.754396&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;11.212195&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;94.054712
</pre>

<p>We can see that the throughput peaks at about 94 megabits/sec, which is 
pretty good for a 100 Megabit connection.  We can also see that, for 
small transfer sizes, the round-trip time is dominated by latency.  The 
&ldquo;latency&rdquo; is the same thing as the one-way (1/2 round-trip) 
transit time for a zero-byte packet, which is about 93 microseconds in 
this case.</p>



<h3 id="hd0017003002">CPUstat</h3>

<p>CPUstat is available only for Linux and is installed in the same place 
as NetTest (<code>/opt/VirtualGL/bin</code> by default.)  It measures 
the average, minimum, and peak CPU usage for all processors combined and 
for each processor individually.  On Windows, this same functionality is 
provided in the Windows Performance Monitor, which is part of the 
operating system.  On Solaris, the same data can be obtained through 
<code>vmstat</code>.</p>

<p>CPUstat measures the CPU usage over a given sample period (a few 
seconds) and continuously reports how much the CPU was utilized since 
the last sample period.  Output for a particular sample looks something 
like this:</p>

<pre class="verbatim">
ALL&nbsp;:&nbsp;&nbsp;51.0&nbsp;(Usr=&nbsp;47.5&nbsp;Nice=&nbsp;&nbsp;0.0&nbsp;Sys=&nbsp;&nbsp;3.5)&nbsp;/&nbsp;Min=&nbsp;47.4&nbsp;Max=&nbsp;52.8&nbsp;Avg=&nbsp;50.8
cpu0:&nbsp;&nbsp;20.5&nbsp;(Usr=&nbsp;19.5&nbsp;Nice=&nbsp;&nbsp;0.0&nbsp;Sys=&nbsp;&nbsp;1.0)&nbsp;/&nbsp;Min=&nbsp;19.4&nbsp;Max=&nbsp;88.6&nbsp;Avg=&nbsp;45.7
cpu1:&nbsp;&nbsp;81.5&nbsp;(Usr=&nbsp;75.5&nbsp;Nice=&nbsp;&nbsp;0.0&nbsp;Sys=&nbsp;&nbsp;6.0)&nbsp;/&nbsp;Min=&nbsp;16.6&nbsp;Max=&nbsp;83.5&nbsp;Avg=&nbsp;56.3
</pre>

<p>The first column indicates what percentage of time the CPU was active 
since the last sample period (this is then broken down into what 
percentage of time the CPU spent running user, nice, and system/kernel 
code.)  &ldquo;ALL&rdquo; indicates the average utilization across all 
CPUs since the last sample period.  &ldquo;Min&rdquo;, 
&ldquo;Max&rdquo;, and &ldquo;Avg&rdquo; indicate a running minimum, 
maximum, and average of all samples since CPUstat was started.</p>

<p>Generally, if an application&rsquo;s CPU usage is fairly steady, you can 
run CPUstat for a bit and wait for the Max. and Avg. for the 
&ldquo;ALL&rdquo; category to stabilize, then that will tell you what 
the application&rsquo;s peak and average % CPU utilization is.</p>



<h3 id="hd0017003003">TCBench</h3>

<p>TCBench was born out of the need to compare VirtualGL&rsquo;s 
performance to that of other thin client software, some of which had 
frame spoiling features that could not be disabled.  TCBench measures 
the frame rate of a thin client system as seen from the client&rsquo;s 
point of view.  It does this by attaching to one of the client windows 
and continuously reading back a small area at the center of the window.  
While this may seem to be a somewhat non-rigorous test, experiments have 
shown that, if care is taken to ensure that the application is updating 
the center of the window on every frame (such as in a spin animation), 
TCBench can produce quite accurate results.  It has been sanity checked 
with VirtualGL&rsquo;s internal profiling mechanism and with a variety 
of system-specific techniques, such as monitoring redraw events on the 
client&rsquo;s windowing system.</p>

<p>TCBench is installed in <code>/opt/VirtualGL/bin</code> by default.  For 
Windows users, a native Windows version of TCBench is included in the 
&ldquo;VirtualGL-Utils&rdquo; package, which is distributed alongside 
VirtualGL.  Run <code>tcbench</code> from the command line, and it will 
prompt you to click in the window you want to benchmark.   That window 
should already have an automated animation of some sort running before 
you launch TCBench.  Note that GLXSpheres (see below) is an ideal 
benchmark to use with TCBench, since GLXSpheres draws a new sphere to 
the center of its window on every frame.</p>

<pre class="verbatim">
tcbench&nbsp;-?
</pre>

<p>lists the relevant command-line arguments, which can be used to adjust 
the benchmark time, the sampling rate, and the x and y offset of the 
sampling area within the window.</p>



<h3 id="hd0017003004">GLXSpheres</h3>

<p>GLXSpheres is a benchmark that produces very similar images to 
nVidia&rsquo;s (long-discontinued) SphereMark benchmark.  Back in the 
early days of VirtualGL&rsquo;s existence, it was discovered (quite by 
accident) that SphereMark was a pretty good test of VirtualGL&rsquo;s 
end-to-end performance, because that benchmark generated images with 
about the same proportion of solid color and similar frequency 
components to the images generated by volume visualization applications.</p>

<p>Thus, the goal of GLXSpheres was to create an open source Unix version 
of SphereMark (the original SphereMark was for Windows only) completely 
from scratch.  GLXSpheres does not use any code from the original 
benchmark, but it does attempt to mimic the visual output of the 
original as closely as possible.  GLXSpheres lacks some of the advanced 
rendering features of the original, such as the ability to use vertex 
arrays, but since GLXspheres was primarily designed as a benchmark for 
VirtualGL, display lists are more than fast enough for that purpose.</p>

<p>GLXSpheres has some additional modes that its predecessor lacked, modes 
that are designed specifically to test the performance of various 
VirtualGL features:</p>

<dl class="Description">
    <dt class="Description-1 Description">Stereographic rendering (<code>glxspheres&nbsp;-s</code>)</dt>
    <dd class="Description-1 Description">
    </dd>
    <dt class="Description-1 Description">Overlay rendering (<code>glxspheres&nbsp;-o</code>)</dt>
    <dd class="Description-1 Description">
        This renders text, a moving crosshair cursor, and a block of pixels to 
        an 8-bit transparent overlay while animating the spheres on the 
        underlay.  The color map of the overlay is changed periodically.
    </dd>
    <dt class="Description-1 Description">Immediate mode rendering (<code>glxspheres&nbsp;-m</code>)</dt>
    <dd class="Description-1 Description">
        Want to really see the benefit of VirtualGL?  Run 
        <code>glxspheres&nbsp;-m</code> over a remote X connection, then run 
        <code>vglrun&nbsp;-sp&nbsp;glxspheres&nbsp;-m</code> over the same 
        connection and compare. Immediate mode does not use display lists, so 
        when immediate mode OpenGL is rendered indirectly (over a remote X 
        connection), this causes every OpenGL command to be sent as a separate 
        network request to the X server &hellip; with every frame.  Many 
        applications do not use display lists (because the geometry they are 
        rendering is dynamic, or for other reasons), so this test models how 
        such applications might perform when displayed remotely without 
        VirtualGL.
    </dd>
    <dt class="Description-1 Description">Interactive mode (<code>glxspheres&nbsp;-i</code>)</dt>
    <dd class="Description-1 Description">
        In interactive mode, GLXSpheres will wait to draw a frame until it 
        receives a mouse event.  Continuously dragging the mouse in the window 
        should produce a steady frame rate, and this frame rate is a reasonable 
        model of the frame rate that you can achieve when running interactive 
        applications in VirtualGL.  Comparing this interactive frame rate 
        (<code>vglrun&nbsp;glxspheres&nbsp;-i</code>) with the non-interactive 
        frame rate (<code>vglrun&nbsp;-sp&nbsp;glxspheres</code>) allows you to 
        quantify the effect of X latency on the performance of interactive 
        applications in a VirtualGL environment.
    </dd>
</dl>

<p>GLXSpheres is installed in <code>/opt/VirtualGL/bin</code> by default.  
64-bit VirtualGL builds name this program <code>glxspheres64</code> so 
as to allow both a 64-bit and a 32-bit version of GLXSpheres to be 
installed on the same system.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0018"><a name="file018"></a>18&nbsp;The VirtualGL Configuration Dialog</h1>

<p><a name="Config_Dialog"></a></p>

<p>Several of VirtualGL&rsquo;s configuration parameters can be changed on 
the fly once a 3D application has been started.  This is accomplished by 
using the VirtualGL Configuration dialog, which can be popped up by 
holding down the <code>CTRL</code> and <code>SHIFT</code> keys and 
pressing the <code>F9</code> key while any one of the 3D 
application&rsquo;s windows is active.  This displays the following 
dialog box:</p>

<p><img src="configdialog.gif" alt="configdialog" class="inline" id="imgid_1" name="imgid_1"/></p>

<p>You can use this dialog to adjust various image compression and display 
parameters in VirtualGL.  Changes are communicated immediately to 
VirtualGL.</p>

<dl class="Description">
    <dt class="Description-1 Description">Image Compression (Transport)</dt>
    <dd class="Description-1 Description">
        This is a drop-down menu with the following options: <br /><br /> 
        <em>None (X11 Transport)</em> : equivalent to setting 
        <code>VGL_COMPRESS=proxy</code>. This option can be activated at any 
        time, regardless of which transport was active when VirtualGL started. 
        <br /><br /> <em>JPEG (VGL Transport)</em> : equivalent to setting 
        <code>VGL_COMPRESS=jpeg</code>.  This option is only available if the 
        VGL Transport was active when VirtualGL started. <br /><br /> <em>RGB 
        (VGL Transport)</em> : equivalent to setting 
        <code>VGL_COMPRESS=rgb</code>.  This option is only available if the VGL 
        Transport was active when VirtualGL started. <br /><br /> <em>YUV (XV 
        Transport)</em> : equivalent to setting <code>VGL_COMPRESS=xv</code>.  
        This option is only available if the 2D X server has the X Video 
        extension and the X Video implementation supports the YUV420P (AKA 
        &ldquo;I420&rdquo;) pixel format. <br /><br /> <em>YUV (VGL 
        Transport)</em> : equivalent to setting <code>VGL_COMPRESS=yuv</code>.  
        This option is only available if the 2D X server has the X Video 
        extension, the X Video implementation supports the YUV420P (AKA 
        &ldquo;I420&rdquo;) pixel format, and the VGL Transport was active when 
        VirtualGL started. <br /><br /> See Section 
        <a href="#VGL_COMPRESS" class="ref">19.1</a> for more information about 
        the <code>VGL_COMPRESS</code> configuration option.
        <div class="important"><p class="important">
        If an image transport plugin is loaded, then this menu&rsquo;s name changes to &ldquo;Image Compression&rdquo;, and it has options &ldquo;0&rdquo; through &ldquo;10&rdquo;.
        </p></div>
    </dd>
    <dt class="Description-1 Description">Chrominance Subsampling</dt>
    <dd class="Description-1 Description">
        This drop-down menu is active only when using JPEG compression or an 
        image transport plugin.  It has the following options: <br /><br /> 
        <em>Grayscale</em> : equivalent to setting <code>VGL_SUBSAMP=gray</code> 
        <br /><br /> <em>1X</em> : equivalent to setting 
        <code>VGL_SUBSAMP=1x</code> <br /><br /> <em>2X</em> : equivalent to 
        setting <code>VGL_SUBSAMP=2x</code> <br /><br /> <em>4X</em> : 
        equivalent to setting <code>VGL_SUBSAMP=4x</code> <br /><br /> See 
        Section <a href="#VGL_SUBSAMP" class="ref">19.1</a> for more information 
        about the <code>VGL_SUBSAMP</code> configuration option.
        <div class="important"><p class="important">
        If an image transport plugin is loaded, then this menu has two additional options, &ldquo;8X&rdquo; and &ldquo;16X&rdquo;.
        </p></div>
    </dd>
    <dt class="Description-1 Description">JPEG Image Quality</dt>
    <dd class="Description-1 Description">
        This slider gadget is active only when using JPEG compression or an 
        image transport plugin.  It is the equivalent of setting 
        <code>VGL_QUAL</code>.  See Section 
        <a href="#VGL_QUAL" class="ref">19.1</a> for more information about the 
        <code>VGL_QUAL</code> configuration option.
        <div class="important"><p class="important">
        If an image transport plugin is loaded, then this gadget&rsquo;s name changes to &ldquo;Image Quality&rdquo;.
        </p></div>
    </dd>
    <dt class="Description-1 Description">Connection Profile</dt>
    <dd class="Description-1 Description">
        This drop-down menu is active only if the VGL Transport was active when 
        VirtualGL started.  It has the following options: <br /><br /> <em>Low 
        Qual (Low-Bandwidth Network)</em> : Sets the image compression type to 
        JPEG (VGL Transport), sets the Chrominance Subsampling to 4X, and sets 
        the JPEG Image Quality to 30. <br /><br /> <em>Medium Qual</em> : Sets 
        the image compression type to JPEG	(VGL Transport), sets the Chrominance 
        Subsampling to 2X, and sets the JPEG Image Quality to 80. <br /><br /> 
        <em>High Qual (High-Bandwidth Network)</em> : Sets the image compression 
        type to JPEG (VGL Transport), sets the Chrominance Subsampling to 1X, 
        and sets the JPEG Image Quality to 95.
    </dd>
    <dt class="Description-1 Description">Gamma Correction Factor</dt>
    <dd class="Description-1 Description">
        This floating point input gadget is the equivalent of setting 
        <code>VGL_GAMMA</code>.  This enables VirtualGL&rsquo;s internal gamma 
        correction system with the specified gamma correction factor.  See 
        Section <a href="#VGL_GAMMA" class="ref">19.1</a> for more information 
        about the <code>VGL_GAMMA</code> configuration option.
    </dd>
    <dt class="Description-1 Description">Frame Spoiling</dt>
    <dd class="Description-1 Description">
        This toggle button is the equivalent of setting <code>VGL_SPOIL</code>.  
        See Section <a href="#Frame_Spoiling" class="ref">17.2</a> and Section 
        <a href="#VGL_SPOIL" class="ref">19.1</a> for more information about the 
        <code>VGL_SPOIL</code> configuration option.
    </dd>
    <dt class="Description-1 Description">Interframe Comparison</dt>
    <dd class="Description-1 Description">
        This toggle button is the equivalent of setting 
        <code>VGL_INTERFRAME</code>.  See Section 
        <a href="#VGL_INTERFRAME" class="ref">19.1</a> for more information 
        about the <code>VGL_INTERFRAME</code> configuration option.
    </dd>
    <dt class="Description-1 Description">Stereographic Rendering Method</dt>
    <dd class="Description-1 Description">
        This drop-down menu has the following options: <br /><br /> <em>Send 
        Left Eye Only</em> : equivalent to setting <code>VGL_STEREO=left</code>. 
        <br /><br /> <em>Send Right Eye Only</em> : equivalent to setting 
        <code>VGL_STEREO=right</code> <br /><br /> <em>Quad-Buffered (if 
        available)</em> : equivalent to setting <code>VGL_STEREO=quad</code> 
        <br /><br /> <em>Anaglyphic (Red/Cyan)</em> : equivalent to setting 
        <code>VGL_STEREO=rc</code> <br /><br /> <em>Anaglyphic 
        (Green/Magenta)</em> : equivalent to setting <code>VGL_STEREO=gm</code> 
        <br /><br /> <em>Anaglyphic (Blue/Yellow)</em> : equivalent to setting 
        <code>VGL_STEREO=by</code> <br /><br /> <em>Passive (Interleaved)</em> : 
        equivalent to setting <code>VGL_STEREO=i</code> <br /><br /> <em>Passive 
        (Top/Bottom)</em> : equivalent to setting <code>VGL_STEREO=tb</code> 
        <br /><br /> <em>Passive (Side-by-Side)</em> : equivalent to setting 
        <code>VGL_STEREO=ss</code> <br /><br /> See Section 
        <a href="#VGL_STEREO" class="ref">19.1</a> for more information about 
        the <code>VGL_STEREO</code> configuration option.
    </dd>
    <dt class="Description-1 Description">Limit Frames/second</dt>
    <dd class="Description-1 Description">
        This floating point input gadget is the equivalent of setting 
        <code>VGL_FPS</code>.  See Section 
        <a href="#VGL_FPS" class="ref">19.1</a> for more information about the 
        <code>VGL_FPS</code> configuration option.
    </dd>
</dl>

<p>You can set the <code>VGL_GUI</code> environment variable to change the 
key sequence used to pop up the VirtualGL Configuration dialog.  If the 
default of <code>CTRL-SHIFT-F9</code> is not suitable, then set 
<code>VGL_GUI</code> to any combination of <code>ctrl</code>, 
<code>shift</code>, <code>alt</code>, and one of 
<code>f1,&nbsp;f2,...,&nbsp;f12</code> (these are not case sensitive.)  
For example:</p>

<pre class="verbatim">
export&nbsp;VGL_GUI=CTRL-F9
</pre>

<p>will cause the dialog box to pop up whenever <code>CTRL-F9</code> is 
pressed.</p>

<p>To disable the VirtualGL dialog altogether, set <code>VGL_GUI</code> to 
<code>none</code>.</p>

<div class="important"><p class="important">
VirtualGL monitors the application&rsquo;s X event loop to determine whenever a particular key sequence has been pressed.  If an application is not monitoring key press events in its X event loop, then the VirtualGL Configuration dialog might not pop up at all.  There is unfortunately no workaround for this, but it should be a rare occurrence.
</p></div>

<p><br /></p>

<hr class="break" />



<h1 id="hd0019"><a name="file019"></a>19&nbsp;Advanced Configuration</h1>

<p><a name="Advanced_Configuration"></a></p>


<h2 id="hd0019001">19.1&nbsp;Server Settings</h2>

<p>You can control the operation of the VirtualGL faker in four different 
ways. Each method of configuration takes precedence over the previous 
method:</p>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Setting a configuration environment variable globally (for instance, in 
        <code>/etc/profile</code>)
    </li>
    <li class="Ordered-1 Ordered">
        Setting a configuration environment variable on a per-user basis (for 
        instance, in <code>~/.bashrc</code>)
    </li>
    <li class="Ordered-1 Ordered">
        Setting a configuration environment variable only for the current shell 
        session (for instance, <code>export&nbsp;VGL_XXX={whatever}</code>)
    </li>
    <li class="Ordered-1 Ordered">
        Passing a configuration option as an argument to <code>vglrun</code>.  
        This effectively overrides any previous environment variable setting 
        corresponding to that configuration option.
    </li>
</ol>

<p></p>

<div class="important"><p class="important">
If &ldquo;Custom (if supported)&rdquo; is listed as one of the available Image Transports, then this means that image transport plugins are free to handle or ignore the configuration option as they see fit.
</p></div>

<p><a name="VGL_ALLOWINDIRECT"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_ALLOWINDIRECT&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Allow applications to request an indirect OpenGL context</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">0 (all OpenGL contexts use direct rendering, unless rendering to a <a href="#overlays">transparent overlay</a><a name="idx0041"></a>)</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally, when VirtualGL maps a Pbuffer to a window and establishes an 
        OpenGL rendering context with the Pbuffer, it forces direct rendering to 
        be used with this context.  Some 3D applications erroneously try to 
        create indirect OpenGL contexts because they detect that the X display 
        is remote and assume that the 3D rendering commands will be sent over 
        the network.  Thus, VirtualGL normally forces all contexts to be direct 
        in order to prevent severe readback performance degradation with such 
        apps (even on modern 3D adapters, and even when the connection to the 3D 
        X server is local, <code>glReadPixels()</code> can perform very slowly 
        if an indirect OpenGL context is used.) <br /><br /> However, some 
        applications intentionally try to create indirect contexts so that these 
        contexts can be shared, and those apps may not work properly when the 
        contexts are forced to be direct.  For such apps, setting 
        <code>VGL_ALLOWINDIRECT</code> to <code>1</code> will cause VirtualGL to 
        honor the application&rsquo;s request for an indirect OpenGL context.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_CLIENT&nbsp;=&nbsp;</code><em><code>{c}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-cl&nbsp;</code><em><code>{c}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{c}</code></em> = the hostname or IP address of the VirtualGL client</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Automatically set by <code>vglconnect</code> or <code>vglrun</code></td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When using the VGL Transport, <code>VGL_CLIENT</code> should be set to 
        the hostname or IP address of the machine on which 
        <code>vglclient</code> is running. Normally, <code>VGL_CLIENT</code> is 
        set automatically when executing <code>vglconnect</code> or 
        <code>vglrun</code>, so don&rsquo;t override it unless you know what 
        you&rsquo;re doing.
    </dd>
</dl>

<p><a name="VGL_COMPRESS"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_COMPRESS&nbsp;=&nbsp;</code><em><code>proxy&nbsp;|&nbsp;jpeg&nbsp;|&nbsp;rgb&nbsp;|&nbsp;xv&nbsp;|&nbsp;yuv</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-c&nbsp;</code><em><code>proxy&nbsp;|&nbsp;jpeg&nbsp;|&nbsp;rgb&nbsp;|&nbsp;xv&nbsp;|&nbsp;yuv</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Set image transport and image compression type</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">(See description)</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
         <em>proxy</em> = Send images uncompressed using the X11 Transport.  
         This is useful when displaying to a local 2D X server or X proxy (see 
         Section <a href="#X11_Proxy_Usage_Local" class="ref">9.1</a>.) 
         <br /><br /> <em>jpeg</em> = Compress images using JPEG and send using 
         the VGL Transport.  This is useful when displaying to a remote 2D X 
         server (see Chapter <a href="#VGL_Transport_Usage" class="ref">8</a>.) 
         <br /><br /> <em>rgb</em> = Encode images as uncompressed RGB and send 
         using the VGL Transport. This is useful when displaying to a remote 2D 
         X server or X proxy across a very fast network (see Section 
         <a href="#X11_Proxy_Usage_Remote" class="ref">9.2</a>.) <br /><br /> 
         <em>xv</em> = Encode images as YUV420P (planar YUV with 4X chrominance 
         subsampling) and display them to the 2D X server using the XV 
         Transport. This transport is designed for use with X proxies that 
         support the X Video extension (see Chapter 
         <a href="#X_Video_Support" class="ref">10</a>.) <br /><br /> 
         <em>yuv</em> = Encode images as YUV420P, send using the VGL Transport, 
         and display on the client machine using the X Video extension.  This 
         greatly reduces the CPU usage on both server and client and uses only 
         about half the network bandwidth as RGB, but the use of 4X chrominance 
         subsampling does produce some visible artifacts (see Chapter 
         <a href="#X_Video_Support" class="ref">10</a>.) <br /><br /> If 
         <code>VGL_COMPRESS</code> is not specified, then the default is set as 
         follows: <br /><br /> If the <code>DISPLAY</code> environment variable 
         begins with <code>:</code> or <code>unix:</code>, then VirtualGL 
         assumes that the X display connection is local and will default to 
         using <em>proxy</em> compression. <br /><br /> If VirtualGL detects 
         that the 2D X server is remote, then it will default to using 
         <em>jpeg</em> compression.
        <div class="important"><p class="important">
        If an image transport plugin is being used, then you can set <code>VGL_COMPRESS</code> to any numeric value &gt;= 0 (Default value = 0.)  The plugin can choose to respond to this value as it sees fit.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_DEFAULTFBCONFIG"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_DEFAULTFBCONFIG&nbsp;=&nbsp;</code><em><code>{attrib_list}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{attrib_list}</code></em> = Attributes of the default GLX framebuffer config, which VirtualGL uses if a 3D application does not call <code>glXChooseVisual()</code> to specify the visual attributes it desires</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">None</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally, a Unix OpenGL application would call the 
        <code>glXChooseVisual()</code> function to obtain an X11 visual with a 
        desired set of OpenGL attributes (such as a specific Z buffer depth, 
        etc.)  The application would then use that X visual when creating an X 
        window for OpenGL rendering.  VirtualGL&rsquo;s fundamental purpose is 
        to redirect OpenGL rendering from a window on one X server (the 2D X 
        server) to a Pbuffer on another X server (the 3D X server.)  Thus, for 
        every OpenGL-enabled X visual that the application tries to obtain, 
        VirtualGL needs to obtain an equivalent &ldquo;GLX FB config&rdquo;, 
        which is like an X visual for Pbuffers.  VirtualGL does this by 
        intercepting <code>glXChooseVisual()</code> and using the attributes 
        passed to that function to build an attribute list for 
        <code>glXChooseFBConfig()</code>, which is called on the 3D X server.  
        The FB config returned from <code>glXChooseFBConfig()</code> is mapped 
        internally to an X visual on the 2D X server, and that visual is 
        returned from <code>glXChooseVisual()</code>.  The FB config is later 
        used when creating the Pbuffer that backs a 3D application window. 
        <br /><br /> In rare cases, an application may choose to implement its 
        own visual selection mechanism rather than call 
        <code>glXChooseVisual()</code>.  Such applications will iterate through 
        the list of X visuals and examine the OpenGL attributes of each using 
        <code>glXGetConfig()</code>.  The problem is this:  whereas in a 
        &ldquo;normal&rdquo; GLX environment, there would be a 1:1 
        correspondence between X visuals and GLX FB configs, in 
        VirtualGL&rsquo;s split rendering environment, X visuals are on the 2D X 
        server and GLX FB configs are on the 3D X server. Thus, if an 
        application calls <code>glXGetConfig()</code> before calling 
        <code>glXChooseVisual()</code>, VirtualGL has not yet mapped the X 
        visual in question to a GLX FB config, and furthermore, VirtualGL has no 
        idea what type of visual the application is looking for.  In such cases, 
        VGL has to map the visual to a default FB config.  Since this default FB 
        config is very basic, if the application is hunting for a visual with a 
        particular OpenGL attribute (such as an alpha channel or a stencil 
        buffer), then it may fail to find one. <br /><br /> 
        <code>VGL_DEFAULTFBCONFIG</code> allows the user to specify the 
        attributes of VirtualGL&rsquo;s default FB config.  This may be 
        necessary to make certain applications work, if those applications do 
        not use <code>glXChooseVisual()</code> to obtain a visual.  The 
        attribute list is specified in the same way that you would specify an 
        attribute list for <code>glXChooseFBConfig()</code>.  Example: 
        <code>VGL_DEFAULTFBCONFIG&nbsp;=&nbsp;GLX_ALPHA_SIZE,8,GLX_STENCIL_SIZE,8</code>.  
        See <a href="#Application_Recipes">Application 
        Recipes</a><a name="idx0042"></a> for a list of applications that are 
        known to require the use of this configuration option.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_DISPLAY&nbsp;=&nbsp;</code><em><code>{d}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-d&nbsp;</code><em><code>{d}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{d}</code></em> = the X display to use for 3D rendering</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">:0</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If the VirtualGL server has multiple GPUs, each attached to a separate X 
        screen or a separate X server, then you can use this option to specify 
        which GPU should be used for 3D rendering.  For instance, setting 
        <code>VGL_DISPLAY</code> to (or invoking <code>vglrun&nbsp;-d</code> 
        with) <code>:0.1</code> would cause VirtualGL to redirect all of the 3D 
        rendering from the application to a GPU attached to Screen 1 on X 
        display :0.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_EXCLUDE&nbsp;=&nbsp;</code><em><code>{d1[,d2,d3,...]}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{d1[,d2,d3,...]}</code></em> = A comma-separated list of X displays for which the VirtualGL interposer should be bypassed</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">None</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        In certain parallel rendering applications, it may be desirable to 
        directly access multiple GPUs from within worker threads and to disable 
        VirtualGL for those threads while leaving VirtualGL enabled for the main 
        thread, which displays the final rendered result from all of the 
        workers. <br /><br /> The <code>VGL_EXCLUDE</code> environment variable 
        specifies a list of X display names (for instance, &ldquo;:0.1&rdquo;) 
        for which VirtualGL should not interpose any X11, GLX, OpenGL, or XCB 
        calls.  In other words, VirtualGL treats these displays as 3D X servers 
        instead of 2D X servers and does not attempt to redirect 3D rendering 
        away from them.  When an X display connection is opened using 
        <code>XOpenDisplay()</code>, VirtualGL checks if the display name 
        appears in the exclude list, and if so, all subsequent X11, GLX, OpenGL, 
        and XCB calls intended for that display are allowed to pass through 
        unimpeded.  This variable is re-checked every time 
        <code>XOpenDisplay()</code> is called, so it can be set dynamically from 
        within an application.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_FAKEXCB&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-xcb</code> / <code>+xcb</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable XCB interposer</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Qt 5 uses XCB instead of Xlib to perform all non-OpenGL X11-related 
        operations.  Thus, in order to support Qt 5 applications, VirtualGL has 
        to interpose enough of the XCB API to allow it to intercept window 
        resize events and to make Qt 5 believe that a GLX extension is present, 
        even when the 2D X server doesn&rsquo;t support GLX.  The XCB interposer 
        in this release of VirtualGL should be non-intrusive, and thus it is 
        enabled by default, and this option is provided only for troubleshooting 
        purposes. You shouldn&rsquo;t need to disable the XCB interposer unless 
        unforeseen problems are encountered.
    </dd>
</dl>

<p><a name="VGL_FORCEALPHA"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_FORCEALPHA&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Force the Pbuffers used for 3D rendering to have an 8-bit alpha channel</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>VGL_FORCEALPHA=1</code> if PBO readback mode is used, <code>VGL_FORCEALPHA=0</code> otherwise</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally, VirtualGL will create Pbuffers whose attributes match those of 
        the visuals requested by the 3D application.  Setting 
        <code>VGL_FORCEALPHA</code> to <code>1</code> causes VirtualGL to always 
        create Pbuffers with alpha channels.  This means that a 32-bit-per-pixel 
        (BGRA) Pbuffer will be created if the application requests a 
        24-bit-per-pixel visual. <br /><br /> The primary purpose of this option 
        is to work around a limitation of certain consumer-grade GPUs, whereby 
        the pixel format requested by the pixel readback operation must match 
        the pixel format of the Pbuffer in order for pixel buffer objects (PBOs) 
        to behave correctly.  Since displaying to an X proxy typically requires 
        VirtualGL to read back pixels in the BGRA format, enabling 
        <code>VGL_FORCEALPHA</code> might be necessary in order to use PBO 
        readback mode with the afore-mentioned GPUs (as of this writing, nVidia 
        GeForce adapters are known to require this.)  See the 
        <a href="#VGL_READBACK"><code>VGL_READBACK</code></a><a name="idx0043"></a> 
        option for further information.
        <div class="important"><p class="important">
        <code>VGL_FORCEALPHA</code> overrides the application&rsquo;s choice of visuals.  It has no effect if the application is not explicitly choosing a visual.  In that case, use <a href="#VGL_DEFAULTFBCONFIG"><code>VGL_DEFAULTFBCONFIG</code></a><a name="idx0044"></a> instead.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_FPS"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_FPS&nbsp;=&nbsp;</code><em><code>{f}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-fps&nbsp;</code><em><code>{f}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Limit the end-to-end frame rate to <em><code>{f}</code></em> frames/second, where <em><code>{f}</code></em> is a floating point number &gt; 0.0</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, X11, XV, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">0.0 (No limit)</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        This option prevents VirtualGL from sending frames at a rate faster than 
        the specified limit.  It can be used, for instance, as a crude way to 
        control network bandwidth or CPU usage in multi-user environments in 
        which those resources are constrained. <br /><br /> If frame spoiling is 
        disabled, then setting <code>VGL_FPS</code> effectively limits the 
        server&rsquo;s 3D rendering frame rate as well.
    </dd>
</dl>

<p><a name="VGL_GAMMA"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_GAMMA&nbsp;=&nbsp;</code><em><code>{g}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-gamma&nbsp;</code><em><code>{g}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Specify gamma correction factor</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">1.00 (no gamma correction)</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        &ldquo;Gamma&rdquo; refers to the relationship between the intensity of 
        light that your computer&rsquo;s monitor is instructed to display and 
        the intensity that it actually displays.  The curve is an exponential 
        curve of the form <em>Y = X<sup>G</sup></em>, where X is between 0 and 
        1.  G is called the &ldquo;gamma&rdquo; of the monitor.  PC monitors and 
        TVs usually have a gamma of around 2.2. <br /><br /> Some of the math 
        involved in 3D rendering assumes a linear gamma (G = 1.0), so 
        technically speaking, 3D applications will not display with mathematical 
        correctness unless the pixels are &ldquo;gamma corrected&rdquo; to 
        counterbalance the non-linear response curve of the monitor.  However, 
        some systems do not have any form of built-in gamma correction, so the 
        applications developed for such systems have usually been designed to 
        display properly without gamma correction.  Gamma correction involves 
        passing pixels through a function of the form <em>X = 
        W<sup>1/G</sup></em>, where G is the &ldquo;gamma correction 
        factor&rdquo; and should be equal to the gamma of the monitor.  So, the 
        final output is <em>Y = X<sup>G</sup> = (W<sup>1/G</sup>)<sup>G</sup> = 
        W</em>, which describes a linear relationship between the intensity of 
        the pixels drawn by the application and the intensity of the pixels 
        displayed by the monitor. <br /><br /> If <code>VGL_GAMMA</code> is set 
        to an arbitrary floating point value, then VirtualGL will perform gamma 
        correction on all of the rendered 3D images from the application, using 
        the specified value as the gamma correction factor.  You can also 
        specify a negative value to apply a &ldquo;de-gamma&rdquo; function.  
        Specifying a gamma correction factor of G (where G &lt; 0) is equivalent 
        to specifying a gamma correction factor of -1/G.
    </dd>
</dl>

<p><a name="VGL_GLFLUSHTRIGGER"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_GLFLUSHTRIGGER&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable reading back and sending the front buffer contents whenever the 3D application calls <code>glFlush()</code> while rendering to the front buffer</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        <code>glFlush()</code> is a sort of &ldquo;asynchronous 
        synchronization&rdquo; command.  It flushes the OpenGL command buffers, 
        which generally has the effect of ensuring that the commands have been 
        delivered to the GPU. However, unlike <code>glFinish()</code>, 
        <code>glFlush()</code> does not wait until the commands have been 
        rendered before it returns. <br /><br /> The use of 
        <code>glFlush()</code> can vary widely from application to application. 
        When doing front buffer rendering, some applications call 
        <code>glFlush()</code> after each object is rendered.  Some call it only 
        at the end of the frame.  Others call <code>glFlush()</code> much more 
        often, even as frequently as every time a few primitives are rendered.  
        This creates problems for VirtualGL, since it has to guess what the 
        application is intending to do.  Not all applications that use front 
        buffer rendering call <code>glFinish()</code> to signal the end of a 
        frame, so VirtualGL cannot usually get away with ignoring 
        <code>glFlush()</code>.  However, some applications call 
        <code>glFlush()</code> so often that VirtualGL cannot get away with 
        reading back/sending a frame every time <code>glFlush()</code> is 
        called, either (see 
        <a href="#VGL_SPOILLAST">VGL_SPOILLAST</a><a name="idx0045"></a> for 
        more information on how VirtualGL tries to handle this, under normal 
        circumstances.) <br /><br /> Some 3D applications use 
        <code>glFlush()</code> very liberally and intend for it to be an 
        intermediate rather than a final synchronization command.  Such 
        applications will call <code>glFinish()</code> after a sequence of 
        <code>glFlush()</code> calls, so for those applications, reading back 
        and sending the rendered 3D image in response to <code>glFlush()</code> 
        calls is a waste of resources and can sometimes create visual artifacts 
        (for instance, if the application clears the front buffer with a 
        particular color, calls <code>glFlush()</code>, then clears it again 
        with another color.  We wouldn&rsquo;t mention it if it hadn&rsquo;t 
        happened before.)  For such applications, setting 
        <code>VGL_GLFLUSHTRIGGER</code> to <code>0</code> should make them 
        display properly in VirtualGL.  See 
        <a href="#Application_Recipes">Application 
        Recipes</a><a name="idx0046"></a> for a list of applications that are 
        known to require this.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_GLLIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate OpenGL library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally VirtualGL will call the <code>glXGetProcAddress()</code> or 
        <code>glXGetProcAddressARB()</code> function in the OpenGL library 
        against which it or the 3D application was linked (usually 
        <code>libGL.so.1</code>, in the system library path), and VGL will use 
        that function to load any	other &ldquo;real&rdquo; OpenGL or GLX 
        functions that it needs to call (&ldquo;real&rdquo; as opposed to the 
        &ldquo;fake&rdquo;, or &ldquo;interposed&rdquo;, versions of those 
        functions that VirtualGL provides, which often modify the arguments or 
        perform other operations before calling the &ldquo;real&rdquo; 
        functions.)  You can use the <code>VGL_GLLIB</code> environment variable 
        to specify the path of a dynamic library from which VirtualGL should 
        load &ldquo;real&rdquo; GLX and OpenGL functions. <br /><br /> You 
        shouldn&rsquo;t need to change this unless something doesn&rsquo;t work.  
        However, setting this environment variable is potentially useful if one 
        wishes to insert another OpenGL interposer between VirtualGL and the 
        system&rsquo;s OpenGL library.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_GUI&nbsp;=&nbsp;</code><em><code>{k}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{k}</code></em> = the key sequence used to pop up the VirtualGL Configuration dialog, or <code>none</code> to disable the dialog</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">shift-ctrl-f9</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        VirtualGL will normally monitor an application&rsquo;s X event queue and 
        pop up the VirtualGL Configuration dialog whenever 
        <code>CTRL-SHIFT-F9</code> is pressed.  In the event that this 
        interferes with a key sequence that the application is already using, 
        then you can redefine the key sequence used to pop up the VirtualGL 
        Configuration dialog by setting <code>VGL_GUI</code> to some combination 
        of <code>shift</code>, <code>ctrl</code>, <code>alt</code>, and one of 
        <code>f1,&nbsp;f2,&nbsp;...,&nbsp;f12</code>. You can also set 
        <code>VGL_GUI</code> to <code>none</code> to disable the configuration 
        dialog altogether.  See Chapter 
        <a href="#Config_Dialog" class="ref">18</a> for more details.
    </dd>
</dl>

<p><a name="VGL_INTERFRAME"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_INTERFRAME&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Enable or disable interframe image comparison</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL (JPEG, RGB), Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The VGL Transport will normally compare each frame with the previous 
        frame and send only the portions of the image that have changed. Setting 
        <code>VGL_INTERFRAME</code> to <code>0</code> disables this behavior. 
        <br /><br /> This setting was introduced in order to work around a 
        specific application interaction issue, but since a proper fix for that 
        issue was introduced in VirtualGL 2.1.1, this option isn&rsquo;t really 
        useful anymore.
        <div class="important"><p class="important">
        When using the VGL Transport, interframe comparison is affected by the <a href="#VGL_TILESIZE"><code>VGL_TILESIZE</code></a><a name="idx0047"></a> option
        </p></div>
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_LOG&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Redirect all messages from VirtualGL to a log file specified by <em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Print all messages to stderr</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Setting this environment variable to the pathname of a log file on the 
        VirtualGL server will cause VirtualGL to redirect all of its messages 
        (including profiling and trace output) to the specified log file rather 
        than to stderr.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_LOGO&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Enable or disable the display of a VGL logo in the 3D window(s)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Setting <code>VGL_LOGO</code> to <code>1</code> will cause VirtualGL to 
        display a small logo in the bottom right-hand corner of all of the 
        application&rsquo;s 3D windows.  This is meant as a debugging tool to 
        allow users to determine whether or not VirtualGL is active.
    </dd>
</dl>

<p><a name="VGL_NPROCS"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_NPROCS&nbsp;=&nbsp;</code><em><code>{n}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-np&nbsp;</code><em><code>{n}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{n}</code></em> = the number of CPUs to use for multi-threaded compression</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL (JPEG, RGB), Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">1</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The VGL Transport can divide the task of compressing each frame among 
        multiple server CPUs.  This might speed up the overall throughput in 
        rare circumstances in which the server CPUs are significantly slower 
        than the client CPUs. <br /><br /> VirtualGL will not allow more than 4 
        CPUs total to be used for compression, nor will it allow you to set this 
        parameter to a value greater than the number of CPUs in the system.
        <div class="important"><p class="important">
        When using the VGL Transport, multi-threaded compression is affected by the <a href="#VGL_TILESIZE"><code>VGL_TILESIZE</code></a><a name="idx0048"></a> option
        </p></div>
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_PORT&nbsp;=&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-p&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{p}</code></em> = the TCP port to use when connecting to the VirtualGL Client</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Read from X property stored by VirtualGL Client</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The connection port for the VGL Transport is normally determined by 
        reading an X property that <code>vglclient</code> stores on the 2D X 
        server, so don&rsquo;t override this unless you know what you&rsquo;re 
        doing.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_PROFILE&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-pr</code> / <code>+pr</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable profiling output</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, X11, XV, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If profiling output is enabled, then VirtualGL will continuously 
        benchmark itself and periodically print out the throughput of various 
        stages in its image pipeline. <br /><br /> See Chapter 
        <a href="#Perf_Measurement" class="ref">17</a> for more details.
    </dd>
</dl>

<p><a name="VGL_QUAL"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_QUAL&nbsp;=&nbsp;</code><em><code>{q}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-q&nbsp;</code><em><code>{q}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{q}</code></em> = the JPEG compression quality, 1 &lt;= <em><code>{q}</code></em> &lt;= 100</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL (JPEG), Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">95</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        In digital images, &ldquo;frequency&rdquo; refers to how quickly the 
        color changes between light and dark as you move either horizontally or 
        vertically in the image.  Images with very sharp, bright features on a 
        dark background, for instance, consist of both low-frequency and 
        high-frequency components, whereas images with smooth transitions 
        between neighboring pixels contain only low-frequency components.  JPEG 
        compression works by breaking down the image into its constituent 
        frequencies and then throwing out the highest of these frequencies.  The 
        JPEG image &ldquo;quality&rdquo; determines which frequencies are thrown 
        out.  A JPEG quality of 1 throws out all but the lowest frequencies and 
        thus produces a very impressionistic, but generally not very useful, 
        compressed image.  A JPEG quality of 100 retains all frequencies in the 
        original image (but, due to roundoff errors, the compressed image is 
        still not completely lossless.) <br /><br /> Because the human eye 
        usually cannot detect the highest frequencies in the image, and often 
        because the image lacks those high-frequency elements to begin with, a 
        sufficiently high JPEG quality setting can produce a &ldquo;perceptually 
        lossless&rdquo; image.  A &ldquo;perceptually lossless&rdquo; image 
        contains a small amount of mathematical error when compared to the 
        original image, but this error is so small that, under normal 
        circumstances, human vision cannot detect it.  The threshold quality 
        level at which JPEG compression becomes perceptually lossless is 
        different for each image, but experiments with various visual difference 
        benchmarks (such as 
        <span class="remote"><a href="http://www.mpi-inf.mpg.de/resources/hdr/vdp/" class="remote">HDR-VDP</a></span><a name="idx0049"></a>) 
        suggest that	a JPEG quality of 95 is sufficient to guarantee perceptual 
        losslessness for the types of applications (volume visualization apps, 
        in particular) in which image quality is critical.  As with any 
        benchmarks, Your Mileage May Vary. Those who are particularly paranoid 
        about image quality can set the JPEG quality to 100 or use RGB encoding, 
        but a fast network is required for both. <br />
        <div class="important"><p class="important">
        If using an image transport plugin, then this setting need not necessarily correspond to JPEG image quality.  The plugin can choose to respond to the <code>VGL_QUAL</code> option as it sees fit.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_READBACK"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_READBACK&nbsp;=&nbsp;</code><em><code>none&nbsp;|&nbsp;pbo&nbsp;|&nbsp;sync</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Specify the method used by VirtualGL to read back the 3D pixels from the 3D graphics adapter</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">pbo</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
    </dd>
</dl>
<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        <em>none</em> = Do not read back the 3D pixels at all.  On rare 
        occasions, it might be desirable to have VirtualGL redirect OpenGL 
        rendering from an application&rsquo;s window into a Pbuffer but not 
        automatically read back and send the rendered pixels.  Some applications 
        have their own mechanisms for reading back the rendered pixels, so 
        setting <code>VGL_READBACK=none</code> disables VirtualGL&rsquo;s 
        readback mechanism and prevents duplication of effort. <br /><br /> This 
        option was developed initially to support running 
        <span class="remote"><a href="http://www.paraview.org/" class="remote">ParaView</a></span><a name="idx0050"></a> 
        in parallel using MPI.  ParaView/MPI normally uses MPI Processes 1 
        through N as rendering servers, each rendering a portion of the geometry 
        into a separate window on a separate X display. ParaView reads back 
        these server windows and composites the pixels into the main application 
        window, which is controlled by MPI Process 0.  By creating a script that 
        passes a different value of <code>VGL_DISPLAY</code> and 
        <code>VGL_READBACK</code> to each MPI process, it is possible to make 
        all of the ParaView server processes render to off-screen buffers on 
        different GPUs while preventing VirtualGL from displaying any pixels 
        except those generated by Process 0. <br /><br />
    </li>
    <li class="Itemize-1 Itemize asterisk">
        <em>pbo</em> = PBO readback mode.  Attempt to use pixel buffer objects 
        (PBOs) to read back the 3D pixels from the GPU.  A PBO is an opaque 
        memory buffer managed by OpenGL, so it can be locked down for direct DMA 
        transfers.  This improves readback performance as well as makes the 
        readback operation non-blocking.  Because PBOs are managed buffers, 
        VirtualGL has to perform an additional memory copy to transfer the 
        pixels out of the PBO and into the image transport&rsquo;s buffer.  
        However, on high-end GPUs, PBO readback mode will still generally 
        perform better than synchronous readback mode, even with this additional 
        memory copy.  Further, since the non-blocking nature of PBO readback 
        reduces the load on the GPU, PBOs can improve performance dramatically 
        when multiple simultaneous users are sharing a professional-grade GPU. 
        <br /><br /> As of this writing, some nVidia GeForce adapters will fall 
        back to using blocking readbacks if the pixel format requested in the 
        pixel read operation does not match the pixel format of the Pbuffer.  If 
        VirtualGL detects that this is occurring&ndash; that is, if PBOs are no 
        longer behaving asynchronously&ndash; then VGL will fall back to 
        synchronous readback mode until the next time the compression  type is 
        changed.  If you are using an X proxy, then this situation could occur 
        because the X proxy&rsquo;s virtual framebuffer is BGRA but, unless the 
        application has requested an alpha channel, its Pbuffer is likely BGR.  
        In this specific case, setting the 
        <a href="#VGL_FORCEALPHA"><code>VGL_FORCEALPHA</code></a><a name="idx0051"></a> 
        option to <code>1</code> could alleviate the issue. <br /><br />
    </li>
    <li class="Itemize-1 Itemize asterisk">
        <em>sync</em> = Synchronous readback mode.  This disables the use of 
        PBOs altogether, which causes VirtualGL to always use blocking pixel 
        readback operations. <br /><br /> Setting <code>VGL_VERBOSE=1</code> 
        will cause VirtualGL to print the current readback mode being used, as 
        well as the pixel format requested by the readback operation and the 
        pixel format of the Pbuffer.  Additionally, a notification will be 
        printed if VirtualGL falls back from PBO readback mode to synchronous 
        readback mode.
    </li>
</ul>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_REFRESHRATE&nbsp;=&nbsp;</code><em><code>{r}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{r}</code></em> = the &ldquo;virtual&rdquo; refresh rate, in Hz, for the GLX_EXT_swap_control and GLX_SGI_swap_control extensions</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">60.0</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The GLX_EXT_swap_control and GLX_SGI_swap_control extensions allow 
        applications to specify that buffer swaps should be synchronized with 
        the refresh rate of the monitor.  When one of these extensions is used, 
        <code>glXSwapBuffers()</code> will not return until a specified number 
        of refreshes (the &ldquo;swap interval&rdquo;) has occurred.  Although 
        refresh rate has no meaning when rendering into an off-screen buffer, 
        VirtualGL still emulates the swap control extensions so that 
        applications can control their own frame rate (this is often used by 
        games, for instance, in which maintaining a constant frame rate is 
        important.)  VirtualGL uses an internal timer to emulate the refresh 
        rate, and setting <code>VGL_REFRESHRATE</code> changes the interval of 
        that timer.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SAMPLES&nbsp;=&nbsp;</code><em><code>{s}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-ms&nbsp;</code><em><code>{s}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Force OpenGL multisampling to be enabled with <em><code>{s}</code></em> samples.  <em><code>{s}</code></em> = 0 to force OpenGL multisampling to be disabled.</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Allow the 3D application to determine the level of multisampling</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        This option was added primarily because certain vendor-specific methods 
        of enabling full-scene antialiasing at a global level (such as 
        nVidia&rsquo;s <code>__GL_FSAA_MODE</code> environment variable) do not 
        work with Pbuffers and, subsequently, do not work with VirtualGL.  If 
        <code>VGL_SAMPLES</code> is &gt; 0, then VirtualGL will attempt to 
        create Pbuffers with the specified number (or a greater number) of 
        samples.  This effectively forces the 3D application to render with the 
        specified multisampling level, as if the application had explicitly 
        passed attributes of <code>GLX_SAMPLES</code>, <em><code>{s}</code></em> 
        to <code>glXChooseVisual()</code>.  If <code>VGL_SAMPLES</code> is 
        <code>0</code>, then VirtualGL forces multisampling to be disabled, even 
        if the 3D application explicitly tries to enable it.
        <div class="important"><p class="important">
        <code>VGL_SAMPLES</code> overrides the application&rsquo;s choice of visuals.  It has no effect if the application is not explicitly choosing a visual.  In that case, use <a href="#VGL_DEFAULTFBCONFIG"><code>VGL_DEFAULTFBCONFIG</code></a><a name="idx0052"></a> instead.
        </p></div>
        <div class="important"><p class="important">
        Multisampling cannot be used with Pixmap rendering.  Any application that uses Pixmap rendering will fail if <code>VGL_SAMPLES</code> is set to a value other than 0.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_SPOIL"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SPOIL&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-sp</code> / <code>+sp</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable frame spoiling</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, X11, XV, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        In remote display environments, the mouse movement is generally sampled 
        at least 40 and sometimes 60 times per second.  Therefore, unless 
        VirtualGL is able to deliver at least that number of frames per second, 
        the movement of a 3D scene will appear to lag behind the mouse motion.  
        This is because the server is trying to render a new frame for every 
        mouse motion event, but if the image transport and (if applicable) the 
        client cannot process the frames fast enough, the server&rsquo;s TCP 
        buffers quickly fill up, causing increased delay in the delivery of each 
        frame. VirtualGL&rsquo;s default behavior is to compensate for this by 
        dropping (spoiling) each frame that the transport isn&rsquo;t ready to 
        receive.  This ensures that the movement of the 3D scene will appear to 
        &ldquo;keep up&rdquo; with the mouse, even though not all rendered 
        frames are actually being delivered. <br /><br /> Frame spoiling is 
        usually necessary with interactive applications, but it should be turned 
        off when running benchmarks or other non-interactive applications.  
        Turning off frame spoiling will force every frame rendered on the server 
        to be delivered through the image transport, and thus the frame rate 
        reported by OpenGL benchmarks will accurately reflect the end-to-end 
        performance of VirtualGL (though, in X proxy environments, this may 
        still not accurately reflect the frame rate seen by the user.  See 
        Section <a href="#Frame_Spoiling" class="ref">17.2</a>.)  Disabling 
        frame spoiling also prevents non-interactive applications from wasting 
        graphics resources by rendering frames that will never be seen.
    </dd>
</dl>

<p><a name="VGL_SPOILLAST"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SPOILLAST&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable &ldquo;spoil last&rdquo; frame spoiling algorithm for frames triggered by <code>glFlush()</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, X11, XV, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        VirtualGL will normally read back a rendered 3D image if the 3D 
        application calls <code>glXSwapBuffers()</code> while rendering to the 
        back buffer or if the 3D application calls <code>glFinish()</code>, 
        <code>glFlush()</code>, or <code>glXWaitGL()</code> while rendering to 
        the front buffer.  When frame spoiling is enabled and the image 
        transport is busy compressing/sending a frame, the newly-rendered frame 
        is normally promoted to the head of the queue, and the rest of the 
        frames in the queue are &ldquo;spoiled&rdquo; (discarded.)  This 
        algorithm, called &ldquo;spoil first&rdquo;, ensures that when a frame 
        is actually delivered through the image transport (rather than spoiled), 
        the delivered frame will be the most recently rendered frame.  However, 
        this algorithm requires that VirtualGL read back every frame that the 
        application renders, even if the frame is ultimately discarded. 
        <br /><br /> Some applications call <code>glFlush()</code> many 
        thousands of times per frame while rendering to the front buffer.  Thus, 
        VirtualGL&rsquo;s default behavior is to use a different spoiling 
        algorithm, &ldquo;spoil last&rdquo;, to process frames triggered by 
        <code>glFlush()</code> calls.  &ldquo;Spoil last&rdquo; discards the 
        most recently rendered frame if the image transport is busy.  Thus, the 
        only frames that are read back from the Pbuffer are the frames that are 
        actually delivered through the image transport.  However, there is no 
        guarantee in this case that the delivered frame will be the most 
        recently rendered frame, so applications that perform front buffer 
        rendering and call <code>glFlush()</code> in response to an interactive 
        operation may not display properly.  For such applications, setting the 
        <code>VGL_SPOILLAST</code> environment variable to <code>0</code> prior 
        to launching the application with <code>vglrun</code> will cause the 
        &ldquo;spoil first&rdquo; algorithm to be used for all frame triggers, 
        including <code>glFlush()</code>.  This should fix the display problem, 
        at the expense of increased load on the GPU (because VirtualGL is now 
        reading back the rendered 3D image every time <code>glFlush()</code> is 
        called.)  See <a href="#Application_Recipes">Application 
        Recipes</a><a name="idx0053"></a> for a list of applications that are 
        known to require this.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SSL&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-s</code> / <code>+s</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable SSL encryption of the image transport</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Enabling this option causes the VGL Transport to be tunneled through a 
        secure socket layer (SSL.)
        <div class="important"><p class="important">
        This option has no effect unless both the VirtualGL server and client were built with OpenSSL support.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_STEREO"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_STEREO&nbsp;=&nbsp;</code><em><code>left&nbsp;|&nbsp;right&nbsp;|&nbsp;quad&nbsp;|&nbsp;rc&nbsp;|&nbsp;gm&nbsp;|&nbsp;by&nbsp;|&nbsp;i&nbsp;|&nbsp;tb&nbsp;|&nbsp;ss</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-st&nbsp;</code><em><code>left&nbsp;|&nbsp;right&nbsp;|&nbsp;quad&nbsp;|&nbsp;rc&nbsp;|&nbsp;gm&nbsp;|&nbsp;by&nbsp;|&nbsp;i&nbsp;|&nbsp;tb&nbsp;|&nbsp;ss</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Specify the delivery method for stereo images</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">quad</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
         <em>left</em> = When an application renders a stereo frame, send only 
         the left eye buffer <br /><br /> <em>right</em> = When an application 
         renders a stereo frame, send only the right eye buffer <br /><br /> 
         <em>quad</em> = Attempt to use quad-buffered stereo, which will result 
         in a pair of images being sent to the VirtualGL Client for every frame.  
         Using quad-buffered stereo requires the VGL Transport (or a transport 
         plugin that can handle stereo image pairs.)  Using quad-buffered stereo 
         with the VGL Transport also requires that the 2D X server support 
         OpenGL and be connected to a GPU that supports stereo rendering.  The 
         2D X server should additionally be configured to export stereo visuals.  
         Quad-buffered stereo is not supported when using the VGL Transport with 
         YUV encoding.  If quad-buffered stereo is requested but the transport 
         or the client does not support it, then VirtualGL will fall back to 
         using anaglyphic stereo. <br /><br /> <em>rc</em> = Use Red/Cyan 
         (anaglyphic) stereo, even if quad-buffered is available <br /><br /> 
         <em>gm</em> = Use Green/Magenta (anaglyphic) stereo, even if 
         quad-buffered is available <br /><br /> <em>by</em> = Use Blue/Yellow 
         (anaglyphic) stereo, even if quad-buffered is available <br /><br /> 
         <em>i</em> = Use Interleaved (passive) stereo, even if quad-buffered is 
         available <br /><br /> <em>tb</em> = Use Top/Bottom (passive) stereo, 
         even if quad-buffered is available <br /><br /> <em>ss</em> = Use 
         Side-by-Side (passive) stereo, even if quad-buffered is available 
         <br /><br /> See Chapter <a href="#Advanced_OpenGL" class="ref">16</a> 
         for more details.
    </dd>
</dl>

<p><a name="VGL_SUBSAMP"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SUBSAMP&nbsp;=&nbsp;</code><em><code>gray&nbsp;|&nbsp;1x&nbsp;|&nbsp;2x&nbsp;|&nbsp;4x&nbsp;|&nbsp;8x&nbsp;|&nbsp;16x</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-samp&nbsp;</code><em><code>gray&nbsp;|&nbsp;1x&nbsp;|&nbsp;2x&nbsp;|&nbsp;4x&nbsp;|&nbsp;8x&nbsp;|&nbsp;16x</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Specify the level of chrominance subsampling in the JPEG image compressor</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL (JPEG), Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">1x</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When an image is compressed using JPEG, each pixel in the image is first 
        converted from RGB (Red/Green/Blue) to YCbCr.  An RGB pixel has three 
        values that specify the amounts of red, green, and blue that make up the 
        pixel&rsquo;s color.  A YCbCr pixel has three values that specify the 
        overall brightness of the pixel (Y, or &ldquo;luminance&rdquo;) and the 
        overall color of the pixel (Cb and Cr, or &ldquo;chrominance&rdquo;.)
        <div class="important"><p class="important">
        NOTE: in the digital world, the terms &ldquo;YCbCr&rdquo; and &ldquo;YUV&rdquo; are often used interchangeably.  Per the convention of the image processing and digital video communities, we use &ldquo;YCbCr&rdquo; when discussing JPEG compression and &ldquo;YUV&rdquo; when discussing video formats, but they are really the same thing.
        </p></div>
        Since the human eye is less sensitive to changes in color than it is to 
        changes in brightness, the chrominance components for some of the pixels 
        can be discarded without much noticeable loss in image quality.  This 
        technique, called &ldquo;chrominance subsampling&rdquo;, significantly 
        reduces the size of the compressed image. <br /><br /> <em>1x</em> = no 
        chrominance subsampling <br /><br /> <em>2x</em> = discard the 
        chrominance components for every other pixel along the image&rsquo;s X 
        direction (this is also known as &ldquo;4:2:2&rdquo; or 
        &ldquo;2:1&rdquo; subsampling.) All else being equal, 2x subsampling 
        generally reduces the image size by about 20-25% when compared to no 
        subsampling.<br /> <br /> <em>4x</em> = discard the chrominance 
        components for every other pixel along both the X and Y directions of 
        the image (this is also known as &ldquo;4:2:0&rdquo; or 
        &ldquo;2:2&rdquo; subsampling.)   All else being equal, 4x subsampling 
        generally reduces the image size by about 35-40% when compared to no 
        subsampling. <br /><br /> <em>8x</em> = discard the chrominance 
        components for 3 out of every 4 pixels along the image&rsquo;s X 
        direction and half the pixels along the image&rsquo;s Y direction (this 
        is also known as &ldquo;4:1:0&rdquo; or &ldquo;4:2&rdquo; subsampling.)  
        <em>This option is available only when using an image transport plugin 
        that supports it.</em> <br /><br /> <em>16x</em> = discard the 
        chrominance components for 3 out of every 4 pixels along both the X and 
        Y directions of the image (this is also known as &ldquo;4:4&rdquo; 
        subsampling.)  <em>This option is available only when using an image 
        transport plugin that supports it.</em> <br /><br /> <em>gray</em> = 
        discard all chrominance components.  This is useful when running 
        applications (such as medical visualization applications) that are 
        already generating grayscale images. <br /><br /> Subsampling artifacts 
        are less noticeable with volume data, since it usually only contains 256 
        colors to begin with, but narrow, aliased lines and other sharp features 
        on a black background will tend to produce very noticeable artifacts 
        when subsampling is enabled. <br /><br /> The axis indicator from a 
        popular visualization app displayed with 1x, 2x, and 4x chrominance 
        subsampling (respectively):<br /> 
        <img src="444.gif" alt="444" class="inline" id="imgid_2" name="imgid_2"/><img src="422.gif" alt="422" class="inline" id="imgid_3" name="imgid_3"/><img src="411.gif" alt="411" class="inline" id="imgid_4" name="imgid_4"/> 
        <br />
        <div class="important"><p class="important">
        If using an image transport plugin, then this setting need not necessarily correspond to JPEG chrominance subsampling.  How the plugin responds to the <code>VGL_SUBSAMP</code> option is implementation-specific.
        </p></div>
    </dd>
</dl>

<p><a name="VGL_SYNC"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_SYNC&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-sync</code> / <code>+sync</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable strict 2D/3D synchronization</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL, X11, XV, Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally, VirtualGL&rsquo;s operation is asynchronous from the point of 
        view of the application.  The application swaps the buffers or calls 
        <code>glFinish()</code> or <code>glFlush()</code> or 
        <code>glXWaitGL()</code>, and VirtualGL will read back the Pbuffer and 
        deliver the pixels to the 2D X server &hellip; eventually. This is fine 
        for the vast majority of applications, but it does not strictly conform 
        to the GLX spec.  Technically speaking, when an application calls 
        <code>glXWaitGL()</code> or <code>glFinish()</code>, it is well within 
        its rights to expect the 3D image to be immediately available in the X 
        window. Fortunately, very few applications actually do expect this, but 
        on rare occasions, an application may try to use 
        <code>XGetImage()</code> or other X11 functions to obtain a bitmap of 
        the pixels that were rendered by OpenGL. Enabling <code>VGL_SYNC</code> 
        is a somewhat extreme measure that may be needed to make such 
        applications display properly with VirtualGL.  It was developed 
        initially as a way to pass the GLX conformance suite 
        (<code>conformx</code>, specifically), but at least one commercial 
        application is known to require it as well (see 
        <a href="#Application_Recipes">Application 
        Recipes</a><a name="idx0054"></a>.)<br /><br />When 
        <code>VGL_SYNC</code> is enabled, every call to <code>glFinish()</code>, 
        <code>glXWaitGL()</code>, and <code>glXSwapBuffers()</code> (and 
        <code>glFlush()</code>, if 
        <a href="#VGL_GLFLUSHTRIGGER">VGL_GLFLUSHTRIGGER</a><a name="idx0055"></a> 
        is enabled) will cause the contents of the Pbuffer to be read back and 
        <em>synchronously</em> drawn into the application&rsquo;s window 
        <em>using the X11 Transport and no frame spoiling</em>.  The call to 
        <code>glFinish()</code>, <code>glXWaitGL()</code>, 
        <code>glFlush()</code>, or <code>glXSwapBuffers()</code> will not return 
        until VirtualGL has verified that the pixels have been delivered into 
        the application&rsquo;s window.  As such, this mode can have potentially 
        dire effects on performance when used with a remote 2D X server.  It is 
        strongly recommended that <code>VGL_SYNC</code> be used only in 
        conjunction with an X proxy running on the same server as VirtualGL.
        <div class="important"><p class="important">
        If an image transport plugin is being used, then VirtualGL does not automatically enable the X11 Transport or disable frame spoiling when <code>VGL_SYNC</code> is set.  This allows the plugin to handle synchronous image delivery as it sees fit (or to simply ignore this option.)
        </p></div>
    </dd>
</dl>

<p><a name="VGL_TILESIZE"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_TILESIZE&nbsp;=&nbsp;</code><em><code>{t}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{t}</code></em> = the image tile size (<em><code>{t}</code></em> x <em><code>{t}</code></em> pixels) to use for multi-threaded compression and interframe comparison (8 &lt;= <em><code>{t}</code></em> &lt;= 1024)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">VGL (JPEG, RGB), Custom (if supported)</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">256</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally, the VGL Transport will divide an OpenGL window into 
        equal-sized square tiles, compare each tile vs. the same tile in the 
        previous frame, then compress and send only the tiles that have changed 
        (assuming <a href="#VGL_INTERFRAME">interframe 
        comparison</a><a name="idx0056"></a> is enabled.)  The VGL Transport 
        will also divide up the task of compressing these tiles among the 
        available CPUs in a round robin fashion, if multi-threaded compression 
        is enabled (see 
        <a href="#VGL_NPROCS">VGL_NPROCS</a><a name="idx0057"></a>.) 
        <br /><br /> There are several tradeoffs that must be considered when 
        choosing a tile size: <br /><br /> <em>Parallel scalability:</em> 
        <ul class="Itemize"><li class="Itemize-0">
            Smaller tiles can more easily be divided up among multiple CPUs. If 
            the 
            tile size if too large, then there may not be enough tiles to go 
            around.
        </li></ul> <br /> <em>Compression efficiency:</em> 
        <ul class="Itemize"><li class="Itemize-0">
            There is a certain amount of fixed CPU overhead required when 
            compressing images, so compressing larger tiles makes more efficient 
            use 
            of the CPUs and increases the aggregate throughput of the compressor.
        </li></ul> <br /> <em>Inter-frame optimization:</em> 
        <ul class="Itemize"><li class="Itemize-0">
            When using smaller tiles, there is more of a chance that a given 
            tile 
            will remain unchanged from frame to frame and thus not need to be 
            re-transmitted to the client.
        </li></ul> <br /> <em>Network efficiency:</em> 
        <ul class="Itemize"><li class="Itemize-0">
            Each tile has a certain amount of fixed overhead required to 
            represent 
            it on the network.  Thus, using smaller tiles will increase the 
            total 
            number of tiles per frame, which will increase the total network 
            usage.
        </li></ul> <br /> 256x256 was chosen as the default because, in 
        experiments, it provided the best balance between scalability and 
        efficiency on the platforms that VirtualGL supports.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_TRACE&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-tr</code> / <code>+tr</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable tracing</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When tracing is enabled, VirtualGL will log all calls to the GLX and X11 
        functions it is intercepting, as well as the arguments, return values, 
        and execution times for those functions.  This is useful when diagnosing 
        interaction problems between VirtualGL and a particular OpenGL 
        application.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_TRANSPORT&nbsp;=&nbsp;</code><em><code>{t}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-trans&nbsp;</code><em><code>{t}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Use an image transport plugin</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">None</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If this option is specified, then VirtualGL will attempt to load an 
        image transport plugin contained in a dynamic library named 
        <code>libtransvgl_</code><em><code>{t}</code></em><code>.so</code> 
        located in the dynamic linker path.  See Chapter 
        <a href="#Transport_Plugins" class="ref">11</a> for more information.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_TRAPX11&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable VirtualGL&rsquo;s X11 error handler</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If an application does not install its own X11 error handler, then the 
        default X11 error handler is used, thus causing the application to exit 
        if an X11 error occurs.  Enabling the <code>VGL_TRAPX11</code> option 
        will cause VirtualGL to install its own X11 error handler, which prints 
        a warning message but allows the application to continue running.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_VERBOSE&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-v</code> / <code>+v</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable verbose VirtualGL messages</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When verbose mode is enabled, VirtualGL will reveal some of the 
        decisions it is making behind the scenes, such as which type of X11 
        drawing it is using, etc.  This can be helpful when diagnosing 
        performance problems.
    </dd>
</dl>

<p><a name="VGL_WM"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_WM&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglrun</code> argument</td>
    <td class="standard"><code>-wm</code> / <code>+wm</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable window manager mode</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When window manager mode is enabled, VirtualGL will disable some of its 
        internal features that interfere with the correct operation of 3D window 
        managers such as compiz.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_X11LIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate X11 library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Normally VirtualGL will use the X11 library against which it was linked 
        (usually <code>libX11.so.6</code>, in the system library path) to load 
        any	&ldquo;real&rdquo; X11 functions that it needs to call 
        (&ldquo;real&rdquo; as opposed to the &ldquo;fake&rdquo;, or 
        &ldquo;interposed&rdquo;, versions of those functions that VirtualGL 
        provides, which often modify the arguments or perform other operations 
        before calling the &ldquo;real&rdquo; functions.)  You can use the 
        <code>VGL_X11LIB</code> environment variable to specify the path of a 
        dynamic library from which VirtualGL should load &ldquo;real&rdquo; X11 
        functions. <br /><br /> You shouldn&rsquo;t need to muck with this 
        unless something doesn&rsquo;t work.  However, it is potentially useful 
        if one wishes to insert another X11 interposer between VirtualGL and the 
        system&rsquo;s X11 library.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XCBLIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate XCB library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>libxcb.so.1</code> in the system library path</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Specifies the path of a dynamic library from which VirtualGL should load 
        &ldquo;real&rdquo; XCB functions.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XCBATOMLIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate xcb-atom library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>libxcb-atom.so.0</code> or <code>libxcb-atom.so.1</code> in the system library path</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Specifies the path of a dynamic library from which VirtualGL should load 
        &ldquo;real&rdquo; XCB atom functions.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XCBGLXLIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate xcb-glx library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>libxcb-glx.so.0</code> in the system library path</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Specifies the path of a dynamic library from which VirtualGL should load 
        &ldquo;real&rdquo; XCB GLX functions.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XCBKEYSYMSLIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate xcb-keysyms library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>libxcb-keysyms.so.0</code> or <code>libxcb-keysyms.so.1</code> in the system library path</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Specifies the path of a dynamic library from which VirtualGL should load 
        &ldquo;real&rdquo; XCB keysyms functions.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XCBX11LIB&nbsp;=&nbsp;</code><em><code>{l}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{l}</code></em> = the location of an alternate X11-xcb library</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>libX11-xcb.so.1</code> in the system library path</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Specifies the path of a dynamic library from which VirtualGL should load 
        &ldquo;real&rdquo; X11 XCB functions.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_XVENDOR&nbsp;=&nbsp;</code><em><code>{v}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{v}</code></em> = a fake X11 vendor string to return when the application calls <code>XServerVendor()</code> or <code>ServerVendor()</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Image Transports</td>
    <td class="standard">All</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        Some applications expect the X11 vendor string to contain a particular 
        value, which the application (sometimes erroneously) uses to figure out 
        whether it is being displayed to a local or a remote X server. This 
        setting allows you to fool such applications into thinking that they are 
        being	displayed to a &ldquo;local&rdquo; X server rather than a remote 
        one.
    </dd>
</dl>



<h2 id="hd0019002">19.2&nbsp;Client Settings</h2>

<p>These settings control the VirtualGL Client, which is used only with the 
VGL Transport.  <code>vglclient</code> is normally launched 
automatically from <code>vglconnect</code> and should not require any 
further configuration except in exotic circumstances.  These settings 
are meant only for advanced users or those wishing to build additional 
infrastructure around VirtualGL.</p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGLCLIENT_DRAWMODE&nbsp;=&nbsp;</code><em><code>ogl&nbsp;|&nbsp;x11</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglclient</code> argument</td>
    <td class="standard"><code>-gl</code> / <code>-x</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Specify the method used to draw pixels into the application window</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard"><code>x11</code></td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If the client machine has a GPU, then it may be faster in some rare 
        instances to draw pixels using OpenGL rather than using 2D (X11) 
        commands.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGLCLIENT_LISTEN&nbsp;=&nbsp;</code><em><code>sslonly&nbsp;|&nbsp;nossl</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglclient</code> argument</td>
    <td class="standard"><code>-sslonly</code> / <code>-nossl</code></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Accept only unencrypted or only SSL connections from the VirtualGL server</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Accept both SSL and unencrypted connections</td>
  </tr>
</table>
</div>


<div class="important"><p class="important">
This option is available only if the VirtualGL client was built with OpenSSL support.
</p></div>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGLCLIENT_PORT&nbsp;=&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglclient</code> argument</td>
    <td class="standard"><code>-port&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{p}</code></em> = TCP port on which to listen for unencrypted connections from the VirtualGL server</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Automatically select a free port</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The default behavior for <code>vglclient</code> is to first try 
        listening for unencrypted connections on port 4242, to maintain backward 
        compatibility with VirtualGL v2.0.x.  If port 4242 is not available, 
        then <code>vglclient</code> will try to find a free port in the range of 
        4200-4299.  If none of those ports is available, then 
        <code>vglclient</code> will request a free port from the operating 
        system. <br /><br /> Setting this option circumvents the automatic 
        behavior described above and causes <code>vglclient</code> to listen 
        only on the specified TCP port.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_PROFILE&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable profiling output</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        If profiling output is enabled, then VirtualGL will continuously 
        benchmark itself and periodically print out the throughput of various 
        stages in its image pipelines. <br /><br /> See Chapter 
        <a href="#Perf_Measurement" class="ref">17</a> for more details.
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGLCLIENT_SSLPORT&nbsp;=&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard"><code>vglclient</code> argument</td>
    <td class="standard"><code>-sslport&nbsp;</code><em><code>{p}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard"><em><code>{p}</code></em> = TCP port on which to listen for SSL connections from the VirtualGL server</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Automatically select a free port</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        The default behavior for <code>vglclient</code> is to first try 
        listening for SSL connections on port 4243, to maintain backward 
        compatibility with VirtualGL v2.0.x.  If port 4243 is not available, 
        then <code>vglclient</code> will try to find a free port in the range of 
        4200-4299.  If none of those ports is available, then 
        <code>vglclient</code> will request a free port from the operating 
        system. <br /><br /> Setting this option circumvents the automatic 
        behavior described above and causes <code>vglclient</code> to listen 
        only on the specified TCP port.
        <div class="important"><p class="important">
        This option is available only if the VirtualGL client was built with OpenSSL support.
        </p></div>
    </dd>
</dl>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Environment Variable</td>
    <td class="standard"><code>VGL_VERBOSE&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable verbose VirtualGL messages</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Disabled</td>
  </tr>
</table>
</div>


<dl class="Description">
    <dt class="Description-1 Description">Description</dt>
    <dd class="Description-1 Description">
        When verbose mode is enabled, VirtualGL will reveal some of the 
        decisions it is making behind the scenes, such as which type of X11 
        drawing it is using, etc.  This can be helpful when diagnosing 
        performance problems.
    </dd>
</dl>

<p><br /></p>


</body>
</html>

